tmdremote Command and Live-Event Guide

1. Purpose and scope

tmdremote.exe is the command-line companion to Tyberis Audio Tracker. Use it to inspect and change application settings, manage fingerprints, control configured live input streams, observe live recognition activity, or recognize MP3 and WAV files directly.

It is installed beside Tyberis Audio Tracker.exe and normally controls the running application for the current Windows user. The usual location is %ProgramFiles%\Tyberis Audio Tracker\tmdremote.exe. If Audio Tracker was installed elsewhere, use the copy in that installation directory.

In scope

• One-shot commands for configuration, application control, and fingerprint management.
• File-based recognition against the loaded fingerprint library, without configuring the file as a live input stream.
• Current channel conditions and a follow mode for new recognition activity.
• Human-readable live output, with optional JSON Lines output for software consumers.

Out of scope

• live is not a recognition-history query and does not replay events from before it started.
• The channel-state feed is not a lossless log of every internal state change.
• This page does not document application internals or provide a network API.

Conventions

• Command and item names are ASCII case-insensitive.
• Channel and device IDs are zero-based integers.
• Use normal Windows command-line quoting for arguments containing spaces.
• Successful execution returns exit code 0. Syntax errors return 2. Connection or runtime errors return 1 and write a message to standard error.
• For the live command, use --format jsonl when software will consume the output.

2. Recommended workflow

Choose the smallest command that answers the task. Read current IDs and state before changing configuration, and prefer JSONL whenever another program will consume live output.

1. Confirm Audio Tracker is running. Use tmdremote.exe start if it is not.
2. Discover channels or sources with get channels, get channel all, and get devices.
3. Use a get, set, or fingerprint command for a one-shot task. Chain commands only when their left-to-right order is intentional.
4. Use live --format jsonl for a current snapshot, or add --follow to consume new activity continuously.
5. When following recognition lifecycles, join detect and finalized by recognitionId. Treat match, lost, and idle as separate channel observations.
6. Check the process exit code and standard error before trusting command output.

3. Invocation grammar

tmdremote.exe <COMMAND> [ARGUMENTS...] [<COMMAND> [ARGUMENTS...] ...]

COMMAND = get | set | load | scanmp3 | scanwav | list | listOp |
          info | rename | enable | disable | state | delete | unload |
          loadAll | clear | start | restore | systray | exit | echo |
          space | live

Most commands can be chained in one invocation and execute from left to right. Because live owns the output stream, use it by itself.

4. Command reference

4.1 Configuration and state

get channels
get maxChannels
get channel <ID|all>
get chname <ID|all>
get chdevice <ID|all>
get devices
get logFormat | logFile | fptFolder
get logging | deepSearch | balloonTips | systray
get speaker | highIntegrity | compatibility | scanLevel
get id <FINGERPRINT_NAME>
get upid

set channels <COUNT>
set channel <ID> <on|off>
set chname <ID> <NAME>
set chdevice <ID> <DEVICE_ID>
set logFormat | logFile | fptFolder <VALUE>
set logging | deepSearch | balloonTips | systray <on|off>
set speaker | highIntegrity <on|off>
set scanLevel <low|medium|high>

Changing chdevice stops the channel, changes its source, and restarts it if it was active. The legacy deepSearch setting maps off to Low and on to Medium. Enabling compatibility is unsupported.

4.2 Fingerprints and file recognition

load <FILE>
scanmp3 <FILE>
scanwav <FILE>
list
listOp [s][n][f][l][i]
info <ID>
rename <ID> <NAME>
enable <ID> | disable <ID>
state <ID>
delete <ID> | unload <ID>
loadAll | clear

load creates or loads a fingerprint. scanmp3 and scanwav recognize a file against the loaded library without configuring it as an input stream, creating a fingerprint, or occupying a live channel.

4.3 Application and output

start
restore
systray
exit
echo <TEXT>
space

5. Live command

tmdremote.exe live [-f|--follow] [--channel <ID|all>]
                   [--format <text|jsonl>]

Without --follow, the command emits only the latest condition of each selected channel and exits. It does not reconstruct recognition history.

6. Event contract

6.1 Recognition lifecycle events

For a lifecycle delivered to one subscription, detect precedes finalized. Both objects carry the same opaque recognitionId. Correlate them by this ID, not by title, position, channel timing, or adjacency. The provisional title can differ from the finalized title. Lifecycle events that occurred before the client subscribed are not replayed.

6.2 Channel-state observations

These events are sampled observations of the latest state, not a lossless transition log. Brief intermediate states can be absent. Ordinary position progression is suppressed. Do not require alternating match/lost pairs.

6.3 Explicit non-guarantees

• detect is not guaranteed to appear before a related match.
• lost is not guaranteed to appear before a related finalized.
• finalized is not guaranteed to appear before or after a related idle.
• There may be zero, one, or many match/lost observations between detect and finalized.
• Initial catch-up reports current channel conditions only and emits no synthetic lifecycle history.

7. Live output formats

This section applies only to live. Other commands use their documented text output and do not accept --format.

7.1 JSON Lines

Each line is one complete JSON object. All event objects contain event, channelId, channel, and event-specific fields.

{"event":"detect","recognitionId":"...","channelId":0,"channel":"Radio","title":"Track","positionSeconds":12}
{"event":"match","channelId":0,"channel":"Radio","title":"Track","positionSeconds":12.5,"durationSeconds":240.0,"detail":null}
{"event":"finalized","recognitionId":"...","channelId":0,"channel":"Radio","title":"Track","beginSeconds":12,"endSeconds":32,"durationSeconds":20}

State events use nullable title, positionSeconds, durationSeconds, and detail. Lifecycle numeric fields are integer seconds. State timing fields are floating-point seconds.

7.2 Text

EVENT [ChID: ID] | "channel" | "title-or--" | "timing-or-detail"

Every record retains exactly three pipe separators and three quoted fields. Missing values are -. Backslashes, quotes, pipes, carriage returns, and line feeds inside fields are escaped. Text output does not expose recognitionId; use JSONL when lifecycle correlation is required.

8. Examples

:: Current condition of every channel, then exit
tmdremote.exe live

:: Follow all activity in the recommended machine format
tmdremote.exe live --follow --format jsonl

:: Follow one channel
tmdremote.exe live --follow --channel 0 --format jsonl

:: Execute two non-streaming commands in order
tmdremote.exe set chdevice 0 2 set channel 0 on

:: Preserve an argument containing spaces
tmdremote.exe set chname 0 "Radio One"

9. Errors and compatibility

If Audio Tracker is not running, the command cannot connect and returns non-zero. start starts the desktop application.

If a command cannot connect, check that Audio Tracker is running in the same interactive Windows session and that the command uses the tmdremote.exe installed beside it. Different user contexts can affect access.

Legacy TyMDB scripts can retain a single leading dash on command names. The old TyMDB Pro 3 tmdremote.exe binary is not compatible with Audio Tracker; use the copy installed with Audio Tracker.

Run tmdremote.exe --help for the condensed offline reference shipped with the executable.