Request, grant and revoke talk power

Core keeps client_is_talker, the request's time and reason, and each
channel's needed talk power; clientedit grants or revokes, and "grant
next" picks whoever in our channel asked first, optionally revoking the
rest. The server refuses a request or a grant ("invalid parameter") from
or for a client that can already talk, so both are offered only to those
short of talk power. Grants dropped without an invoker (leaving the
channel, the channel's need changing) are not announced. Verified on a
local 3.13.7 server.

Desktop: Grant/Revoke Talk Power in the client menu, also for several
selected clients; the tree's badges in TeamSpeak's order (granted or
insufficient ahead of the groups, a request after them); the request's
reason in the info panel; log lines; the three talk power hotkeys. The
Self menu's request item shows only while it is needed.
Android: grant/revoke among the client sheet's admin actions, request or
cancel on our own sheet, the same badges in the tree.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-11 01:15:39 +00:00
co-authored by Claude Opus 5.5
parent 204cbd6048
commit a57700959f
23 changed files with 287 additions and 18 deletions
+5 -1
View File
@@ -66,6 +66,10 @@ Android app in [`../android`](../android) does.
on demand); selecting a client shows its **server groups** and **channel group**
(names resolved from the server's group lists), talk power, platform and version.
- **Server-group badge** next to each client's nickname in the tree.
- **Talk power** — request it (Self menu, with a reason, or a hotkey); grant or revoke
it from a client's menu, or grant the next request in our channel by hotkey. The
tree marks granted clients, those short of the channel's needed talk power, and
pending requests, whose reason shows in the info panel.
- **Spacer channels** — TS3 `[spacer]`/`[*spacer]`/`[c/l/r spacer]` names render as
non-interactive separators (fill, centred, aligned).
- Double-click a channel to **join**; right-click a client to **poke**, open a
@@ -314,7 +318,7 @@ swing/ eu.lixko.ts3j.client
- Whisper is received/played but not yet **sendable** from the UI.
- Hotkey actions TeamSpeak offers but this client does not perform yet (listed but
greyed out in the dialog): capture/playback/hotkey profiles and sound packs,
whisper and push-to-whisper, recording, plugins, server groups, talk power, 3D
whisper and push-to-whisper, recording, plugins, server groups, 3D
sound, hardware ("local") microphone mute and the channel-traversal variants
beyond "Switch to Channel".
- Global hotkeys cover Linux and Windows; **macOS has no backend**, so hotkeys there are
@@ -198,11 +198,11 @@ public enum HotkeyAction {
// ----- Misc -----
TALK_POWER_GRANT_NEXT(Category.MISC, 0x01b0, "GrantNextTalkPower",
"Grant Next User Talk Power", true, Argument.NONE, false),
"Grant Next User Talk Power", true, Argument.NONE, true),
TALK_POWER_REQUEST(Category.MISC, 0x01b0, "RequestTalkPower",
"Request Talk Power", true, Argument.NONE, false),
"Request Talk Power", true, Argument.NONE, true),
TALK_POWER_REVOKE_ALL_GRANT_NEXT(Category.MISC, 0x01b0, "RevokeAllAndGrantNext",
"Revoke All And Grant Next User Talk Power", true, Argument.NONE, false),
"Revoke All And Grant Next User Talk Power", true, Argument.NONE, true),
FILEBROWSER(Category.MISC, 0x01d0, "Filebrowser",
"Open Filebrowser on Channel", true, Argument.NONE, true),
@@ -19,6 +19,8 @@ public final class ChannelNode {
public volatile boolean hasPassword;
public volatile boolean permanent;
public volatile int maxClients = -1;
/** The talk power a client needs to talk here ({@code channel_needed_talk_power}). */
public volatile int neededTalkPower;
/** Id of the channel's custom icon in the server's file repository, or 0 for none. */
public volatile long iconId;
/** Whether the server sends us this channel's client list; set from the subscription events. */
@@ -18,6 +18,12 @@ public final class ClientEntry {
public volatile int talkPower;
/** Waiting for a moderator to grant talk power ({@code client_talk_request}). */
public volatile boolean talkRequest;
/** When the request was made, in epoch seconds; 0 when unknown or there is none. */
public volatile long talkRequestTime;
/** The reason given with the request ({@code client_talk_request_msg}). */
public volatile String talkRequestMessage = "";
/** Granted talk power: may talk whatever the channel needs ({@code client_is_talker}). */
public volatile boolean talker;
public volatile int[] serverGroupIds = new int[0];
public volatile int channelGroupId;
@@ -38,7 +38,8 @@ final class ConnectionEventHandler implements TS3Listener {
ClientEntry c = conn.getModel().putClient(e.getClientId(), e.getClientNickname(), e.getClientTargetId());
c.type = safeInt(e, "client_type");
c.talkPower = e.getClientTalkPower();
c.talkRequest = talkRequested(e);
applyTalkRequest(c, e);
c.talker = e.getBoolean("client_is_talker");
c.phoneticNickname = TeamspeakConnection.orEmpty(e.get("client_nickname_phonetic"));
c.inputMuted = e.isClientInputMuted();
c.outputMuted = e.isClientOutputMuted();
@@ -330,7 +331,8 @@ final class ConnectionEventHandler implements TS3Listener {
c.awayMessage = TeamspeakConnection.orEmpty(e.get("client_away_message"));
}
if (has(e, "client_talk_power")) c.talkPower = e.getInt("client_talk_power");
if (has(e, "client_talk_request")) c.talkRequest = talkRequested(e);
if (has(e, "client_talk_request")) applyTalkRequest(c, e);
if (has(e, "client_is_talker")) c.talker = e.getBoolean("client_is_talker");
if (reported(e, "client_nickname_phonetic")) {
c.phoneticNickname = TeamspeakConnection.orEmpty(e.get("client_nickname_phonetic"));
}
@@ -378,10 +380,13 @@ final class ConnectionEventHandler implements TS3Listener {
}
if (has(e, "client_talk_request") && talkRequested(e) && !self) {
conn.sound(SoundEvent.CLIENT_REQUESTED_TALK_POWER, vars);
conn.log(conn.clientLink(c.id) + " requested talk power");
}
if (self && has(e, "client_is_talker")) {
conn.sound(e.getBoolean("client_is_talker")
? SoundEvent.YOU_WERE_GRANTED_TALK_POWER : SoundEvent.YOU_WERE_REVOKED_TALK_POWER, vars);
// Leaving the channel drops the grant too, but without an invoker: that is no news.
if (self && has(e, "client_is_talker") && has(e, "invokerid")) {
boolean granted = e.getBoolean("client_is_talker");
conn.sound(granted ? SoundEvent.YOU_WERE_GRANTED_TALK_POWER : SoundEvent.YOU_WERE_REVOKED_TALK_POWER, vars);
conn.log("Talk Power " + (granted ? "granted" : "revoked") + " by " + invokerName(e));
}
if (!self && has(e, "client_is_recording")) {
boolean recording = e.getBoolean("client_is_recording");
@@ -462,6 +467,7 @@ final class ConnectionEventHandler implements TS3Listener {
if (has(e, "channel_icon_id")) ch.iconId = TeamspeakConnection.safeLong(e, "channel_icon_id");
if (has(e, "channel_flag_password")) ch.hasPassword = e.getBoolean("channel_flag_password");
if (has(e, "channel_flag_permanent")) ch.permanent = e.getBoolean("channel_flag_permanent");
if (has(e, "channel_needed_talk_power")) ch.neededTalkPower = safeInt(e, "channel_needed_talk_power");
if (has(e, "channel_flag_maxclients_unlimited") && e.getBoolean("channel_flag_maxclients_unlimited")) {
ch.maxClients = -1;
} else if (has(e, "channel_maxclients")) {
@@ -709,6 +715,12 @@ final class ConnectionEventHandler implements TS3Listener {
return v != null && !v.isBlank() && !v.trim().equals("0");
}
private static void applyTalkRequest(ClientEntry c, BaseEvent e) {
c.talkRequest = talkRequested(e);
c.talkRequestTime = c.talkRequest ? TeamspeakConnection.safeLong(e, "client_talk_request") : 0;
c.talkRequestMessage = c.talkRequest ? TeamspeakConnection.orEmpty(e.get("client_talk_request_msg")) : "";
}
private static int safeInt(BaseEvent e, String key) {
try {
String v = e.get(key);
@@ -40,6 +40,7 @@ public record Details(String title, List<Field> fields, String description, bool
}
private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
private static final DateTimeFormatter TIME = DateTimeFormatter.ofPattern("HH:mm");
public static Details server(ServerModel model, String address) {
List<Field> fields = new ArrayList<>();
@@ -98,7 +99,9 @@ public record Details(String title, List<Field> fields, String description, bool
? new Field("Channel group", channelGroup.name, List.of(channelGroup))
: new Field("Channel group", "#" + cl.channelGroupId));
if (cl.talkPower != 0) fields.add(Field.minor("Talk power", Integer.toString(cl.talkPower)));
if (cl.talker) fields.add(new Field("Talk power", cl.talkPower + ", granted"));
else if (cl.talkPower != 0) fields.add(Field.minor("Talk power", Integer.toString(cl.talkPower)));
if (cl.talkRequest) fields.add(new Field("Talk request", talkRequest(cl)));
if (!cl.version.isEmpty()) {
fields.add(Field.minor("Version", cl.version + (cl.platform.isEmpty() ? "" : " on " + cl.platform)));
} else if (!cl.platform.isEmpty()) {
@@ -115,6 +118,13 @@ public record Details(String title, List<Field> fields, String description, bool
return new Details(name, fields, cl.description == null ? "" : cl.description, false);
}
private static String talkRequest(ClientEntry cl) {
String message = cl.talkRequestMessage.trim();
if (cl.talkRequestTime <= 0) return message.isEmpty() ? "pending" : message;
String time = TIME.format(Instant.ofEpochSecond(cl.talkRequestTime).atZone(ZoneId.systemDefault()));
return message.isEmpty() ? "since " + time : message + " (" + time + ")";
}
private static long parseLong(String s) {
try {
return s.isEmpty() ? 0 : Long.parseLong(s.trim());
@@ -540,6 +540,34 @@ public final class ServerModel {
return new ArrayList<>(clients.values());
}
/**
* Whether a client is kept from talking: short of its channel's needed talk power and not granted
* any. Only then will the server take a request from them, or a grant for them.
*/
public synchronized boolean lacksTalkPower(ClientEntry client) {
ChannelNode channel = channels.get(client.channelId);
return channel != null && !client.talker && client.talkPower < channel.neededTalkPower;
}
/** The client in a channel who has waited longest for talk power, or null when nobody is asking. */
public synchronized ClientEntry nextTalkRequest(int channelId) {
ClientEntry next = null;
for (ClientEntry c : clients.values()) {
if (c.channelId != channelId || !c.talkRequest) continue;
if (next == null || c.talkRequestTime < next.talkRequestTime) next = c;
}
return next;
}
/** The clients in a channel who were granted talk power. */
public synchronized List<ClientEntry> talkersIn(int channelId) {
List<ClientEntry> out = new ArrayList<>();
for (ClientEntry c : clients.values()) {
if (c.channelId == channelId && c.talker) out.add(c);
}
return out;
}
public synchronized ClientEntry findClientByUniqueId(String uniqueId) {
if (uniqueId == null || uniqueId.isEmpty()) return null;
for (ClientEntry c : clients.values()) {
@@ -993,13 +993,49 @@ public final class TeamspeakConnection implements TS3Listener {
/** @param message the reason shown to moderators; ignored when withdrawing the request */
public void setTalkRequest(boolean request, String message) {
updateSelf(self -> self.talkRequest = request);
updateSelf(self -> {
self.talkRequest = request;
self.talkRequestMessage = request ? message : "";
if (!request) self.talkRequestTime = 0;
});
selfUpdate(cmd -> {
cmd.add(new CommandSingleParameter("client_talk_request", request ? "1" : "0"));
if (request) cmd.add(new CommandSingleParameter("client_talk_request_msg", message));
}, "Talk power request failed");
}
/** Grants or revokes clients' talk power, which lets them talk whatever their channel needs. */
public void setTalker(Collection<Integer> clientIds, boolean talker) {
if (clientIds.isEmpty()) return;
act(talker ? "Error granting talk power: " : "Error revoking talk power: ", sock -> {
for (int id : clientIds) setTalker(sock, id, talker);
});
}
/**
* Grants talk power to whoever in our channel has waited longest for it, first revoking
* it from everyone who has it there when {@code revokeOthers}.
*/
public void grantNextTalkPower(boolean revokeOthers) {
ClientEntry self = model.getClient(selfClientId);
if (self == null) return;
ClientEntry next = model.nextTalkRequest(self.channelId);
List<ClientEntry> talkers = revokeOthers ? model.talkersIn(self.channelId) : List.of();
if (next == null && talkers.isEmpty()) return;
act("Error granting talk power: ", sock -> {
for (ClientEntry c : talkers) {
if (c != next) setTalker(sock, c.id, false);
}
if (next != null) setTalker(sock, next.id, true);
});
}
private static void setTalker(LocalTeamspeakClientSocket sock, int clientId, boolean talker) throws Exception {
sock.executeCommand(new SingleCommand("clientedit", ProtocolRole.CLIENT,
new CommandSingleParameter("clid", Integer.toString(clientId)),
new CommandSingleParameter("client_is_talker", talker ? "1" : "0"))).complete();
}
public void setPhoneticNickname(String phoneticNickname) {
updateSelf(self -> self.phoneticNickname = phoneticNickname);
selfUpdate(cmd -> cmd.add(new CommandSingleParameter("client_nickname_phonetic", phoneticNickname)),
@@ -377,13 +377,18 @@ public final class ServerSession {
/** @param message the reason shown to moderators, may be empty */
public void requestTalkPower(String message) {
if (conn.isConnected()) conn.setTalkRequest(true, message);
if (conn.isConnected() && canRequestTalkPower()) conn.setTalkRequest(true, message);
}
public void cancelTalkRequest() {
if (conn.isConnected()) conn.setTalkRequest(false, "");
}
/** Grants talk power to whoever in our channel asked first, after revoking everyone else's when {@code revokeOthers}. */
public void grantNextTalkPower(boolean revokeOthers) {
if (conn.isConnected()) conn.grantNextTalkPower(revokeOthers);
}
public String phoneticNickname() {
ClientEntry self = self();
return self == null ? "" : self.phoneticNickname;
@@ -666,6 +671,20 @@ public final class ServerSession {
return self != null && !self.avatarFlag.isEmpty();
}
/**
* Whether we may ask for talk power: the server lets us ({@code b_client_request_talker}, offered
* while unknown), and we lack it in our channel, as it refuses the request otherwise.
*/
public boolean canRequestTalkPower() {
ClientEntry self = self();
return permits("b_client_request_talker") && self != null && conn.getModel().lacksTalkPower(self);
}
/** Whether the server lets us grant and revoke talk power ({@code b_client_set_flag_talker}); offered while unknown. */
public boolean canGrantTalkPower() {
return permits("b_client_set_flag_talker");
}
public boolean canMoveClients() {
return hasPower("i_client_move_power");
}
@@ -208,4 +208,35 @@ class ConnectionEventHandlerTest {
events.onChannelDeleted(new ChannelDeletedEvent(fields("notifychanneldeleted cid=2")));
assertNull(model.getChannel(2));
}
@Test
void talkRequestsAndGrantsAsTheServerWordsThem() {
model.putChannel(1, "Lobby", 0, 0);
events.onChannelEdit(new ChannelEditedEvent(fields("notifychanneledited cid=1 reasonid=10 invokerid=2 invokername=admin channel_needed_talk_power=50")));
join(5, "alice", 1);
ClientEntry alice = model.getClient(5);
assertEquals(50, model.getChannel(1).neededTalkPower);
assertTrue(model.lacksTalkPower(alice));
events.onClientChanged(new ClientUpdatedEvent(fields(
"notifyclientupdated clid=5 client_talk_request=1791680640 client_talk_request_msg=let\\sme\\stalk")));
assertTrue(alice.talkRequest);
assertEquals(1791680640L, alice.talkRequestTime);
assertEquals("let me talk", alice.talkRequestMessage);
assertEquals(alice, model.nextTalkRequest(1));
// A grant withdraws the request in the same update.
events.onClientChanged(new ClientUpdatedEvent(fields("notifyclientupdated clid=5 client_talk_request=0"
+ " client_talk_request_msg client_is_talker=1 invokerid=2 invokername=admin invokeruid=x")));
assertFalse(alice.talkRequest);
assertEquals("", alice.talkRequestMessage);
assertTrue(alice.talker);
assertFalse(model.lacksTalkPower(alice));
assertNull(model.nextTalkRequest(1));
assertEquals(List.of(alice), model.talkersIn(1));
// Leaving the channel drops it, without an invoker.
events.onClientChanged(new ClientUpdatedEvent(fields("notifyclientupdated clid=5 client_is_talker=0")));
assertFalse(alice.talker);
}
}
@@ -66,6 +66,15 @@ final class ClientMenu {
menu.add(me);
}
menu.addSeparator();
if (actions.canGrantTalkPower() && client.talker) {
JMenuItem revoke = new JMenuItem("Revoke Talk Power", Icons.of("TALK_POWER_REVOKE"));
revoke.addActionListener(a -> actions.setTalker(List.of(client), false));
menu.add(revoke);
} else if (actions.canGrantTalkPower() && model.lacksTalkPower(client)) {
JMenuItem grant = new JMenuItem("Grant Talk Power", Icons.of("TALK_POWER_GRANT"));
grant.addActionListener(a -> actions.setTalker(List.of(client), true));
menu.add(grant);
}
menu.add(buildServerGroupMenu(client, model, groupIcons, actions));
menu.add(buildChannelGroupMenu(client, model, groupIcons, actions));
menu.addSeparator();
@@ -118,6 +127,18 @@ final class ClientMenu {
moveHere.setEnabled(others);
moveHere.addActionListener(a -> actions.moveClientsToOwnChannel(clients));
menu.add(moveHere);
if (actions.canGrantTalkPower()) {
menu.addSeparator();
JMenuItem grant = new JMenuItem("Grant Talk Power", Icons.of("TALK_POWER_GRANT"));
List<ClientEntry> silent = clients.stream().filter(model::lacksTalkPower).toList();
grant.setEnabled(!silent.isEmpty());
grant.addActionListener(a -> actions.setTalker(silent, true));
menu.add(grant);
JMenuItem revoke = new JMenuItem("Revoke Talk Power", Icons.of("TALK_POWER_REVOKE"));
revoke.setEnabled(clients.stream().anyMatch(c -> c.talker));
revoke.addActionListener(a -> actions.setTalker(clients.stream().filter(c -> c.talker).toList(), false));
menu.add(revoke);
}
return menu;
}
@@ -22,6 +22,7 @@ import java.awt.Rectangle;
import java.awt.RenderingHints;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Set;
@@ -316,6 +317,11 @@ final class DropIndicatorTree extends JTree {
}
}
private static void addIcon(List<Icon> icons, String key) {
Icon icon = key == null ? null : Icons.of(key);
if (icon != null) icons.add(icon);
}
/** The icon strip a row shows on its right, empty when it has none (yet). */
private List<Icon> badgesOf(DefaultMutableTreeNode treeNode) {
Object node = treeNode.getUserObject();
@@ -325,8 +331,12 @@ final class DropIndicatorTree extends JTree {
}
if (node instanceof ClientEntry) {
ClientEntry cl = (ClientEntry) node;
List<Icon> icons = groupIcons.iconsOf(
model.serverGroupsOf(cl.serverGroupIds), model.channelGroup(cl.channelGroupId));
List<Icon> icons = new ArrayList<>();
// TeamSpeak's order: talk power ahead of the groups, a talk request after them.
addIcon(icons, cl.talker ? "IS_TALKER" : model.lacksTalkPower(cl) ? "INPUT_MUTED" : null);
icons.addAll(groupIcons.iconsOf(
model.serverGroupsOf(cl.serverGroupIds), model.channelGroup(cl.channelGroupId)));
addIcon(icons, cl.talkRequest ? "TALK_POWER_REQUEST" : null);
// The country's flag comes last, at the row's edge, as in TeamSpeak.
Icon flag = settings.countryFlags ? CountryFlagIcons.of(cl.country) : null;
if (flag != null) icons.add(flag);
@@ -99,6 +99,10 @@ final class HotkeyActions implements HotkeyEngine.Handler {
for (ServerTab tab : targets) tab.session().stopRecording();
}
case TALK_POWER_REQUEST -> toggleTalkRequest(targets);
case TALK_POWER_GRANT_NEXT -> grantNextTalkPower(targets, false);
case TALK_POWER_REVOKE_ALL_GRANT_NEXT -> grantNextTalkPower(targets, true);
case FILEBROWSER -> frame.browseCurrentChannel();
case SKIN_RELOAD -> frame.reloadSkin();
case BRING_TO_FRONT -> frame.bringToFront();
@@ -139,6 +143,19 @@ final class HotkeyActions implements HotkeyEngine.Handler {
frame.refreshAfterHotkey();
}
/** Asks without a reason, as there is nobody to type one. */
private void toggleTalkRequest(List<ServerTab> targets) {
boolean requested = targets.stream().anyMatch(t -> t.session().isTalkRequested());
for (ServerTab tab : targets) {
if (requested) tab.session().cancelTalkRequest();
else tab.session().requestTalkPower("");
}
}
private void grantNextTalkPower(List<ServerTab> targets, boolean revokeOthers) {
for (ServerTab tab : targets) tab.session().grantNextTalkPower(revokeOthers);
}
private static boolean anyMicMuted(List<ServerTab> tabs) {
return tabs.stream().anyMatch(t -> t.session().isMicMuted());
}
@@ -277,6 +277,11 @@ public final class MainFrame extends JFrame implements ServerTabPane.Listener {
return selected != null && selected.session().isTalkRequested();
}
@Override
public boolean canRequestTalkPower() {
return selected != null && selected.session().canRequestTalkPower();
}
@Override
public void onRequestTalkPower() {
requestTalkPower();
@@ -57,6 +57,9 @@ final class MainMenuBar extends JMenuBar {
/** Whether our talk power request is pending; asked as the Self menu opens. */
boolean isTalkPowerRequested();
/** Whether the current server lets us ask for talk power; asked as the Self menu opens. */
boolean canRequestTalkPower();
/** Requests talk power, or withdraws a pending request. */
void onRequestTalkPower();
@@ -246,7 +249,9 @@ final class MainMenuBar extends JMenuBar {
self.addMenuListener(new MenuListener() {
@Override
public void menuSelected(MenuEvent e) {
showTalkPowerRequested(listener.isTalkPowerRequested());
boolean requested = listener.isTalkPowerRequested();
showTalkPowerRequested(requested);
talkPowerItem.setVisible(requested || listener.canRequestTalkPower());
avatarItem.setVisible(!avatarItem.isEnabled() || listener.canSetAvatar());
deleteAvatarItem.setVisible(listener.hasAvatar());
}
@@ -233,6 +233,16 @@ final class ServerTabTreeActions implements ServerTreePanel.Actions {
return tab.session().canDeleteOtherAvatars();
}
@Override
public boolean canGrantTalkPower() {
return tab.session().canGrantTalkPower();
}
@Override
public void setTalker(List<ClientEntry> clients, boolean talker) {
conn.setTalker(ids(clients), talker);
}
@Override
public void deleteClientAvatar(ClientEntry client) {
tab.avatar().deleteOf(client);
@@ -130,6 +130,11 @@ public final class ServerTreePanel extends JPanel {
/** Whether we may delete other clients' avatars. */
boolean canDeleteOtherAvatars();
/** Whether we may grant and revoke talk power. */
boolean canGrantTalkPower();
void setTalker(List<ClientEntry> clients, boolean talker);
void deleteClientAvatar(ClientEntry client);
/** A new nickname for ourselves, typed into the tree row. */