myTeamSpeak docs: the synced config item, sync edge cases and limits

CONFIG_SYNC.md lists the class 5 config item's fields; none maps onto a
setting of ours, so sync leaves it alone. IMPLEMENTATION.md covers the
session lock, duplicate keys in the account, bookmarks following an
identity's conflict, interrupted runs, and what sync cannot catch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-15 22:04:26 +00:00
co-authored by Claude Opus 5.5
parent f6fbc6e40c
commit 212a4bcdbb
2 changed files with 64 additions and 3 deletions
@@ -0,0 +1,41 @@
# myTeamSpeak config item (class 5)
Apart from bookmarks, identities and the other item classes, TS3 synchronises a small set of settings as
`Item_Class` `CONFIG` (5), `Item_Data` field 21 `Config_data`. It is a fixed schema, not free key/value
pairs, and an account holds a single such item. On the throwaway account it has the uuid
`11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa`, is encrypted like the other items, and decrypts to:
```
Item_Data { 2: "11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa" 6: 5 9: 1790376625
21 { 1: 1 3: 1 } } // default_subscribe_mode = All, show_user_badges = true
```
## Fields
| # | Field | Type | Meaning in TS3 | Ours |
|---|-------|------|----------------|------|
| 1 | `default_subscribe_mode` | int32 | Channel subscription mode for servers without a bookmark of their own; same values as `Bookmark_Data.SubscriptionMode` (0 Undefined, 1 All, 2 Current). Toggled by `onToggleSubscribeMode`; replaced the local `subscribemode.dat`. | None: we always subscribe to all channels |
| 2 | `user_badges` | repeated string | The myTeamSpeak badges the user picked to show, by badge UUID; announced to servers in `client_badges` (`overwolf=n:badges=uuid,…`). | None: we neither pick nor announce badges |
| 3 | `show_user_badges` | bool | Whether the picked badges are shown at all. | None |
| 4 | `global_presence_token` | bytes | myTeamSpeak presence token. | None |
| 5 | `tschat_credentials` | `Chat_Credentials{domain, username, password}` | Login for the old (pre-Matrix) TeamSpeak chat. | None |
| 7 | `tschat_de_data` | repeated `TSCHAT_DE_Data{url, identity, username, server_id, address, port, name}` | Per-server data for the old chat. | None |
Per-bookmark settings of the same kind (`subscription_mode` 19, `subscribed_channel_ids` 20,
`channel_passwords` 21) live in `Bookmark_Data` and survive our edits, which rewrite only the fields we model.
Audio settings (devices, volumes, voice activation, pre-processing) are not synchronised at all. A bookmark only
names its capture and playback profile (`capture_profile` 11, `playback_profile` 12) and sound pack (17); the
profiles themselves stay local.
## Status
None of these fields maps onto a setting our client has, so `MyTeamSpeakSync` leaves class 5 alone: it neither
reads nor writes the config item, and the official client's copy is never touched. Candidates, if the settings are
added first:
- `default_subscribe_mode` (+ bookmark `subscription_mode`): a "subscribe to all / only the current channel" choice.
- `user_badges` / `show_user_badges`: choosing badges needs the badge list from myTeamSpeak (`Badges_Service`,
`UserBadgesList`), so it is more than a sync field.
The rest belongs to the old TeamSpeak chat and presence, which we do not implement.
+23 -3
View File
@@ -16,7 +16,8 @@ that Android 13 lacks (hence `HttpURLConnection`, not `java.net.http`).
was changed elsewhere) `fetch` signs out. All requests share one session (`MyTeamSpeakLogin.request`),
as the official client's do: signed in on first use, again when the service reports it expired
(102/109), ended on sign-out or exit. Signing in for every request gets the account's logins throttled
within a few dozen (seen 2026-10-15: `login` timed out for minutes).
within a few dozen (seen 2026-10-15: `login` timed out for minutes). A sign-in runs under its own lock,
not the login's, so `isSignedIn`/`email`/`username` answer at once on the UI thread while one is under way.
- `MyTeamSpeak.download(Credentials)` — signs in (`authentication/login`), unwraps the item key, pulls
BOOKMARK, IDENTITY and ITEM_FOLDER with one `synchronization/requestServerItems` against an empty
local state (all-zero global and class versions, no details), decrypts every item, then ends the
@@ -36,7 +37,8 @@ Observed on the live account: a bookmark may name its identity by the identity's
of its item UUID; the importer resolves both.
Tests: `MyTsCryptoTest` (captured vectors), `MyTeamSpeakTest` (download against a replayed server built from
the captured login and item), `MyTeamSpeakLoginTest` (persistence, failed sign-in, rejected credentials).
the captured login and item), `MyTeamSpeakLoginTest` (persistence, failed sign-in, rejected credentials, a slow
sign-in), `MyTeamSpeakSyncTest` (two-way sync between installations against a fake account).
## Two-way sync
@@ -54,7 +56,25 @@ identity is each installation's own: `is_default` is not compared, an identity n
uploaded as its default only when it has none, and one brought here becomes ours only when we have none
(otherwise installations flip each other's default on every run). Edits are
written over the item's current `Item_Data` field by field (`ProtobufMessage`), so fields this client does not
model survive.
model survive. The synced settings item (class 5) is listed in `CONFIG_SYNC.md`; none of it maps onto ours.
Cases the plain three-way rule gets wrong:
- The local store holds one identity per key, the account may hold several (the official client can import
the same key twice). Only the first account item for a key is synchronised; the others are kept as the
account has them, never merged into ours (which would write one over the other on the next run). A bookmark
using such a copy connects with the local identity of that key.
- Deleting an identity here clears it from our bookmarks. When the identity was meanwhile changed in the
account (a conflict), a bookmark whose only change is that cleared link does not go out on its own: it
follows the identity's conflict — relinked to the restored identity on "Keep myTeamSpeak's", sent without
it on "Delete".
- A run cut off between `upload` and `apply` (process killed, screen left) needs nothing special: the next
run sees its own uploads as the same on both sides and keeps them.
Known limits: `push` checks the cursors, then stores; another client storing in between is not seen until the
class changes again, as we keep our own class revision as the cursor. The service gives no way to close that
gap. Deletions from elsewhere are carried out like any other change, and deleting an identity deletes its key
file.
### How the service and the official client behave (live, 2026-10-15)