Repository navigation
TCPIP dvk
The Digital Voice Keyer (DVK) stores short voice recordings in the radio and plays them back over the air on demand -- a CQ, an exchange, a callsign. Recordings live in the radio's database, so they survive a restart and are shared by every client connected to the radio. A client can record into a slot from its own transmit audio, preview a slot through its own audio output without transmitting, play a slot on the air, rename or clear a slot, and transfer a slot's audio to or from the client as a WAV file. (v4.0 and later)
DVK is a licensed feature. On a radio without the DVK feature license,
every dvk command fails with 50004001 (see
Licensing).
The radio maintains twelve recording slots with IDs 1 through
12. They are created automatically and are restored at every
restart if missing, so a client does not need to create them. A new or
cleared slot is named Recording <id> (for example Recording 3) and
holds no audio.
| Limit | Value |
|---|---|
| Slots | 12, IDs 1-12 |
| Recording length | 10 seconds. Recording stops automatically and the audio is saved when the limit is reached |
| Name length | 63 bytes, measured before the radio strips the quotes, so a quoted name may be at most 61 characters |
| Name characters | Do not use the double quote (") or the pipe (|). Runs of spaces inside a quoted name collapse to one space |
| Duration units | Milliseconds |
Always pass an ID from 1 to 12. Not every command checks that the slot exists.
The DVK is in one of four states, reported by the status key of the
DVK status line:
| State | Meaning |
|---|---|
| idle | Nothing in progress |
| recording | Audio is being captured into a slot |
| preview | A slot is being played to client audio outputs only. The radio does not key |
| playback | A slot is being transmitted. The radio is keyed by the DVK |
Run one operation at a time: wait for the status to return to idle, or
send the matching stop command, before starting another operation or
before clearing, removing or uploading into a slot. The radio does not
refuse overlapping operations, and starting one while another is in
progress can leave the DVK in an inconsistent state.
Every state change is published to all clients subscribed with
sub dvk all, so a client should drive its user interface
from status rather than from command responses. Playback and preview end
on their own at the end of the recording, and a recording ends on its
own at the 10 second limit; the only notification of these is the status
change back to idle.
dvk rec_start captures the transmit audio of the client that sent the
command, from whichever transmit audio source that client has selected:
| Client TX audio source | What is recorded |
|---|---|
| Radio mic inputs (MIC, BAL, LINE, ACC) | The radio's codec input |
| PC (remote audio) | The client's remote TX audio stream, with +6 dB gain |
| DAX TX | The client's DAX TX stream |
Recording does not key the transmitter. Audio from other clients is ignored.
Starting a recording into a slot discards that slot's previous audio.
The new audio is saved to the radio when the recording stops, and a
recording update carrying the new duration is
published.
dvk playback_start keys the radio and transmits the recording on the
current transmit slice -- the slice designated as the transmitter
with slice set <n> tx=1. Select a transmit slice before starting
playback. The recording replaces the transmit audio from the mic or
other source for the duration of playback, and passes through the
normal transmit signal chain.
-
Keying. Playback keys through the interlock like any other PTT
source. The interlock status reports it as
source=DVK, and all interlock conditions (TX REQ lines, amplifier and antenna interlocks, the transmit timeout) apply to it as they do to a MIC or SW PTT. See interlock. -
Unkeying. The radio unkeys at the end of the recording and on
dvk playback_stop. The DVK keeps its own PTT source asserted while it plays, so releasing a MIC, foot-switch or MOX PTT that was also pressed does not stop playback. Usedvk playback_stop. -
Empty slots. Only start playback or preview of a slot whose
durationis greater than 0. Playing an empty slot returns0, and can leave the radio keyed. - VOX. In v4.2, if VOX is triggered during playback, the radio can remain in transmit after playback ends. Avoid VOX activity during playback, or be ready to unkey the radio.
Preview (dvk preview_start) plays the recording to client audio
outputs -- the speaker/headphone output and remote audio streams -- and
never keys the radio. It is not sent to DAX RX streams.
DVK requires the Digital Voice Keyer feature license. On an unlicensed
radio every dvk command fails with:
| Hex Response | Message | Debug Output / Meaning |
|---|---|---|
| 50004001 | DVK feature is not licensed |
sub dvk all still succeeds on an unlicensed radio, and the radio still
publishes the DVK status and the twelve slots. The enabled key of the
status line is always 1 and does not reflect the license, so a client
should rely on the 50004001 response to detect an unlicensed radio.
A response of 50001000 from a dvk command means the radio could not
parse it: the subcommand is unknown, a required id or name parameter
is missing or malformed, or the name is too long.
Start recording into a slot. See Recording for which audio is captured.
C[D]<seq_number>|dvk rec_start id=<id>
<id> = the slot to record into (1-12)
Example:
C21|dvk rec_start id=3
See Response Format for details on the format of the response messages from the radio
| Hex Response | Message | Debug Output / Meaning |
|---|---|---|
| 00000000 | OK recording started | |
| 50001000 | Missing or invalid id parameter |
|
| 50004001 | DVK feature is not licensed |
Responses
Response Example:
R21|0|
Stop the recording in progress and save it. The slot ID is not needed.
Stopping when nothing is being recorded returns 0.
C[D]<seq_number>|dvk rec_stop
Example:
C22|dvk rec_stop
| Hex Response | Message | Debug Output / Meaning |
|---|---|---|
| 00000000 | OK recording stopped and saved | |
| 50004001 | DVK feature is not licensed |
Responses
Response Example:
R22|0|
Play a slot to client audio outputs without transmitting. Preview stops by itself at the end of the recording.
C[D]<seq_number>|dvk preview_start id=<id>
<id> = the slot to preview (1-12)
Example:
C23|dvk preview_start id=3
| Hex Response | Message | Debug Output / Meaning |
|---|---|---|
| 00000000 | OK preview started | |
| 50001000 | Missing or invalid id parameter |
|
| 50004001 | DVK feature is not licensed | |
| E2000000 | No slot with that ID |
Responses
Response Example:
R23|0|
Stop the preview in progress. Stopping when nothing is being previewed
returns 0.
C[D]<seq_number>|dvk preview_stop
Example:
C24|dvk preview_stop
| Hex Response | Message | Debug Output / Meaning |
|---|---|---|
| 00000000 | OK preview stopped | |
| 50004001 | DVK feature is not licensed |
Responses
Response Example:
R24|0|
Key the radio and transmit a slot on the transmit slice. Playback stops and the radio unkeys by itself at the end of the recording. See Playback and Transmit.
C[D]<seq_number>|dvk playback_start id=<id>
<id> = the slot to transmit (1-12)
Example:
C25|dvk playback_start id=3
| Hex Response | Message | Debug Output / Meaning |
|---|---|---|
| 00000000 | OK playback started | |
| 50001000 | Missing or invalid id parameter |
|
| 50004001 | DVK feature is not licensed | |
| E2000000 | No slot with that ID |
Responses
Response Example:
R25|0|
Stop playback and unkey the radio. Stopping when nothing is playing
returns 0.
C[D]<seq_number>|dvk playback_stop
Example:
C26|dvk playback_stop
| Hex Response | Message | Debug Output / Meaning |
|---|---|---|
| 00000000 | OK playback stopped | |
| 50004001 | DVK feature is not licensed |
Responses
Response Example:
R26|0|
Rename a slot. The name may be changed at any time, whether or not the slot holds audio. Enclose the name in double quotes when it contains spaces.
C[D]<seq_number>|dvk set_name id=<id> name="<name>"
<id> = the slot to rename (1-12)
<name> = the new name, at most 61 characters inside the quotes, with no '"' or '|'
Example:
C27|dvk set_name id=3 name="CQ Contest"
| Hex Response | Message | Debug Output / Meaning |
|---|---|---|
| 00000000 | OK slot renamed | |
| 50001000 | Missing or invalid id or name parameter, or the name is too long |
|
| 50004001 | DVK feature is not licensed | |
| E2000000 | No slot with that ID, or the name was rejected |
Responses
Response Example:
R27|0|
Erase a slot's audio and reset its name to the default
(Recording <id>). The slot itself remains. Stop any recording, preview
or playback of the slot first.
C[D]<seq_number>|dvk clear id=<id>
<id> = the slot to clear (1-12)
Example:
C28|dvk clear id=3
| Hex Response | Message | Debug Output / Meaning |
|---|---|---|
| 00000000 | OK slot cleared | |
| 50001000 | Missing or invalid id parameter |
|
| 50004001 | DVK feature is not licensed | |
| E2000000 | No slot with that ID, or clear failed |
Responses
Response Example:
R28|0|
Transfer a slot's audio from the radio to the client as a WAV file. The response carries the TCP port of the transfer. After responding, the radio waits about half a second and then connects to the client (at the client's IP address, on that port), sends the WAV file, and closes the connection. The client must therefore already be listening on that port. The end of the file is signalled by the radio closing the connection; no length is sent ahead of it.
C[D]<seq_number>|dvk download id=<id>
<id> = the slot to download (1-12)
Example:
C29|dvk download id=3
| Hex Response | Message | Debug Output / Meaning |
|---|---|---|
| 00000000 | 42607 | OK, the radio will connect to the client on port 42607 |
| 50000053 | The file transfer server is busy with another transfer | |
| 50001000 | Missing or invalid id parameter |
|
| 50004001 | DVK feature is not licensed |
Responses
Response Example:
R29|0|42607
The WAV file is 16-bit PCM, two channels, at the radio's audio codec
sample rate. Only download a slot whose duration is greater than 0: if
the slot has no audio file, the radio still responds 0 but never
connects.
Load a slot's audio from a WAV file sent by the client. This is a
two-command sequence. First dvk upload tells the radio which slot the
next DVK file upload is for; then a
file upload of type dvk_recording carries
the file:
- Stop any recording, preview or playback of the slot
- Send
dvk upload id=<id> - Send
file upload <size_in_bytes> dvk_recording. The radio responds with the TCP port, 42607 -
Connect to the radio on that port, send exactly
<size_in_bytes>bytes of the WAV file, and close the connection - When the file has been received, the radio loads it into the slot and
publishes a recording update with the new
duration
Always follow dvk upload with the file upload. The radio accepts only
one pending DVK upload at a time, and further dvk upload commands fail
until the pending one has completed.
C[D]<seq_number>|dvk upload id=<id>
<id> = the slot to load (1-12)
Example:
C30|dvk upload id=3
C31|file upload 160044 dvk_recording
| Hex Response | Message | Debug Output / Meaning |
|---|---|---|
| 00000000 | OK, the next dvk_recording file upload will be loaded into this slot |
|
| 50001000 | Missing or invalid id parameter |
|
| 50004001 | DVK feature is not licensed | |
| E2000000 | A DVK upload is already pending, or the file transfer server is busy |
Responses
Response Example:
R30|0|
R31|0|42607
File requirements:
- Sample rate: must equal the radio's audio codec sample rate. The radio does not resample, so audio at any other rate plays back at the wrong pitch and speed. The simplest way to get the right rate is to match a WAV downloaded from the same radio.
- Channels: only the first (left) channel is used.
If the radio cannot read the file, the slot keeps its previous audio.
The radio does not report this to the client, so compare the duration
in the next recording update with the expected length.
Allocate a new slot with the next unused ID and a default name. The
response carries the new ID and its name, separated by -, and an
added status is published to all subscribed clients.
The radio already provides the twelve standard slots (see Slots) and removes slots outside 1-12 at restart, so a client should use those twelve slots rather than create new ones. This command is reserved for future use.
C[D]<seq_number>|dvk create
Example:
C32|dvk create
| Hex Response | Message | Debug Output / Meaning |
|---|---|---|
| 00000000 | -"" | OK, the new slot's ID and its name |
| 50004001 | DVK feature is not licensed | |
| E2000000 | The slot could not be created |
Responses
Response Example:
R32|0|13-"Recording 13"
Delete a slot entirely, including its audio and name. A deleted status
is published to all subscribed clients. Stop any recording, preview or
playback of the slot first.
A removed slot 1-12 is recreated, empty, at the next restart. This command is reserved for future use; to empty a slot, use clear.
C[D]<seq_number>|dvk remove id=<id>
<id> = the slot to delete
Example:
C33|dvk remove id=3
| Hex Response | Message | Debug Output / Meaning |
|---|---|---|
| 00000000 | OK slot removed | |
| 50001000 | Missing or invalid id parameter |
|
| 50004001 | DVK feature is not licensed | |
| E2000000 | No slot with that ID |
Responses
Response Example:
R33|0|
Subscribe to DVK status. On subscribing, the radio sends the current
DVK status line followed by an added line for every
slot, before the command response. Use unsub
dvk all to stop.
C[D]<seq_number>|sub dvk all
Example:
C20|sub dvk all
| Hex Response | Message | Debug Output / Meaning |
|---|---|---|
| 00000000 | OK subscription registered |
Responses
Response Example:
R20|0|
DVK status lines are sent to clients that have subscribed with
sub dvk all. There are four forms:
S<handle>|dvk status=<state> [id=<id>] enabled=<0|1>
S<handle>|dvk added id=<id> name="<name>" duration=<duration_ms>
S<handle>|dvk deleted id=<id>
S<handle>|dvk id=<id> name="<name>" duration=<duration_ms>
<handle> = a hexadecimal client handle. For a change the radio makes on its own, such as the end of playback, it is not necessarily the client that started the operation
<state> = idle, recording, preview or playback (see Operating States)
<id> = the slot ID. On the status line, present only when the state is not idle
<name> = the slot name, always enclosed in double quotes and possibly containing spaces
<duration_ms> = the length of the slot's audio in milliseconds; 0 when the slot is empty
| Form | Sent when |
|---|---|
| status= | The DVK changes state, including when playback, preview or recording ends on its own, and on sub dvk all
|
| added | A slot is created, and once per slot on sub dvk all. A client may receive added for an ID it already knows; treat it as an update |
| deleted | A slot is removed |
| id= (update) | A slot's name or audio changes: after rec_stop (or the 10 second limit), set_name, clear, or an upload |
The status= line also defines the state disabled, but the radio does
not currently send it, and enabled is currently always 1. A client
should still treat status=disabled or enabled=0 as DVK being
unavailable.
Because the name is quoted and may contain spaces, parse it by finding the opening and closing double quotes rather than by splitting the line on spaces.
Example status lines:
S5A3C2B1F|dvk status=idle enabled=1
S5A3C2B1F|dvk status=playback id=3 enabled=1
S5A3C2B1F|dvk added id=3 name="CQ Contest" duration=4210
S5A3C2B1F|dvk id=3 name="CQ Contest" duration=4210
A client subscribes, names slot 1, records into it, and plays it on the air:
(1) C1|sub dvk all
(2) S5A3C2B1F|dvk status=idle enabled=1
(3) S5A3C2B1F|dvk added id=1 name="Recording 1" duration=0
... (one added line for each of slots 2 through 12)
(4) R1|0|
(5) C2|dvk set_name id=1 name="CQ Contest"
(6) S5A3C2B1F|dvk id=1 name="CQ Contest" duration=0
(7) R2|0|
(8) C3|dvk rec_start id=1
(9) S5A3C2B1F|dvk status=recording id=1 enabled=1
(10) R3|0|
(11) C4|dvk rec_stop
(12) S5A3C2B1F|dvk id=1 name="CQ Contest" duration=4210
(13) S5A3C2B1F|dvk status=idle enabled=1
(14) R4|0|
(15) C5|dvk playback_start id=1
(16) S5A3C2B1F|dvk status=playback id=1 enabled=1
(17) R5|0|
(18) S<handle>|dvk status=idle enabled=1
The client subscribes (1) and receives the current state (2) and every
slot (3) before the response (4). It renames slot 1 (5), and the update
(6) carries the new name. It starts recording (8); the radio captures
the client's transmit audio without keying until the client stops the
recording (11). The radio publishes the saved length, 4.21 seconds (12),
and the return to idle (13). The client then starts playback (15). The
radio keys -- the interlock status shows source=DVK -- and transmits
the recording on the transmit slice. At the end of the recording the
radio unkeys by itself and publishes the return to idle (18), with no
further command from the client.
