diff --git a/ChangeLog b/ChangeLog index 5d6b3b72..efca7a11 100644 --- a/ChangeLog +++ b/ChangeLog @@ -24383,3 +24383,6 @@ 2023-08-25 Fred Gleason * Fixed an error in the invocation specification for the 'Insert Cart' ['PX'] RML in the Operations Guide. +2023-08-29 Fred Gleason + * Refactored the playback, record and mixer commands in the CAE + protocol design document. diff --git a/docs/apis/Makefile.am b/docs/apis/Makefile.am index 1cecb28f..88b5c5ae 100644 --- a/docs/apis/Makefile.am +++ b/docs/apis/Makefile.am @@ -25,7 +25,7 @@ %.html: %.xml xsltproc -o $@ $(DOCBOOK_STYLESHEETS)/xhtml/docbook.xsl $< %.pdf: %.xml - xsltproc $(DOCBOOK_STYLESHEETS)/fo/docbook.xsl $< | fop - -pdf $@ + xsltproc --stringparam toc.section.depth 4 $(DOCBOOK_STYLESHEETS)/fo/docbook.xsl $< | fop - -pdf $@ %.1: %.xml xsltproc $(DOCBOOK_STYLESHEETS)/manpages/docbook.xsl $< %.8: %.xml diff --git a/docs/apis/cae.xml b/docs/apis/cae.xml index 68018194..d9e22b56 100644 --- a/docs/apis/cae.xml +++ b/docs/apis/cae.xml @@ -1,8 +1,7 @@ -
+
Rivendell Core Audio Control Protocol - 0.9.1 Fred @@ -12,1394 +11,1242 @@ - + Overview - Formats used for audio storage are Broadcast Wave Format (BWF), as - specified in - EBU Tech Pub 3285 - with annexes. + Rivendell's core audio engine [CAE] component runs continuously in + the background, handling all realtime audio tasks for Rivendell, including + audio file capture, play-out and manipulation of the relevant audio mixer + controls. It is implemented as the + caed8 program, which is started + and stopped automatically as needed by the + rivendell Systemd service. - Commands to the Core Audio Engine are passed by means of a - TCP SOCK_STREAM connection to TCP port 5005 on the host server. + This document describes the IPC mechanisms by which other components + of Rivendell can interact with CAE. - - Commands have the following general syntax: - - - cmd-code [arg] [...]! - - - - + + The Audio Store + + After importation, all audio referenced by Rivendell is saved in the + audio store, located at + /var/snd/. Audio corresponding to + Rivendell audio cuts as well as Rivendell hosted podcast feeds is kept + in the audio store, organized as follows: + + + Cut Audio + + Files are named according to the scheme: + cartnum_cutnum.wav + where cartnum is the containing cart + number, zero padded to be six digits long and + cutnum is the cut number, zero padded + to be three digits long. For example, a file containing audio for cut + 93 within cart number + 1234 would be contained in a file named + 001234_093.wav. + + + A cut that has been created in the database but has not been populated + with audio (either by importation or realtime capture) will not have + a corresponding file in the audio store. + + + Formats used for cut audio storage are Broadcast Wave Format (BWF), as + specified in + EBU Tech Pub 3285 + with annexes. + + + It is not correct to assume that files ending with a "wav" extension + in their filename necessarily contain PCM16 audio; other audio formats + are possible, including MPEG 1 Layer II. See + + EBU Tech Pub 3285 Supplement 1 + for details. + + + + RSS Item Audio + + Backup copies of the audio for all posted items generated by + Rivendell's podcasting system are named according to the scheme: + feed-id_cast-id.mp3, where feed-id is the integer ID of the RSS feed + to which the item belongs, zero-padded to be six digits long, + and cast-id is the integer ID of the item + itself, padded to be six digits long. For example, a file containing + audio for an item with an feed ID of 1234 and + an item ID of 5678 would be contained in a file + named 001234_005678.mp3 + + All item files contain raw MPEG 1 Layer III frames, optionally + preceded by an ID tag (v2.4). + + + + + + Communicating with the Core Audio Engine + + + Commands to the Core Audio Engine are passed by means of packets sent via + a SOCK_DGRAM socket to UDP port 5005 on the recipient system. + + + + + Command Format + + + Commands are textual, with fields delimited by the ASCII + SPACE character (decimal 32), with each + command encapsulated within its own UDP data packet. They have the + following general syntax: + + cmd-code - - - - A two letter command code, describing the generic action to be - performed - - - - - - arg - - - - Zero or more arguments, delimited by spaces or, if the last - argument, by ! (see below) - - - - - - ! - - - - The ASCII character 33, indicating the end of the command sequence. - - - - - - Unless otherwise specified, the engine will echo back the command with a - + or - before the !, to indicate the success or failure of the command - execution. - - + [opt0 .. optN] + + + All commands sent to and received from CAE must contain the following + session information: + + + + + cmd-code + + + An ASCII string containing two characters in the range + [A-Z], + indicating the type of operation to perform. + + + + + + opt0 .. optN + + + + Zero or more command-specific options. + + + + + + - - Connection Management - - <command>Password</command> - - Pass a password to the server for authentication. - - - PW - password! - - - - - password - - - A password to be supplied before granting the client access. - - - - - Returns: PW +! to indicate success, - PW -! to indicate failure - - - - <command>Drop Connection</command> - - Drop the TCP connection and end the session. - - - DC! - - + Playback Operations - - <command>Load Playback</command> - - Prepare an audio interface to play an audio file. - - - LP card-num - name! - - - - + + Commands + + <command>Start Playback</command> + + Start play-back of a specified audio file, while also creating an + ongoing session that can be operated upon with the remainder of the + commands documented in this section. + + + + PY + pid + serial + pid + serial + cut-name card-num - - - The number of the audio adapter to use. - - - - - name - - - The base name of an existing file in the audio storage filesystem. - - - - - Returns: LP - card-num - name - stream-num - conn-handle! - - - - - stream-num - - - - The stream number selected to be used, or a -1 in case of error. - This is relative to the audio adapter selected. - - - - - - conn-handle - - - - The connection handle. This will be used to refer to the playback - event in all subsequent calls to CAE. - - - - - - - - <command>Unload Playback</command> - - Free an audio playback interface. This will also mute all associated - output stream->output port volume controls. - - - UP conn-handle! - - - - - conn-handle - - - - The connection handle of the playback event, from the - Load Playback call. - - - - - - - - <command>Play Position</command> - - Position the playback pointer. - - - PP conn-handle - position! - - - - - conn-handle - - - - The connection handle of the playback event, from the - Load Playback call. - - - - - - position - - - - Position in file, in milliseconds. - - - - - - - - <command>Play</command> - - Play the loaded file from the current position. - - - PY conn-handle - length - speed - pitch-flag! - - - - - conn-handle - - - - The connection handle of the playback event, from the - Load Playback call. - - - - - - length - - - - Playback length in milliseconds, relative to the current start - position. - - - - - + port-num + start-pos + end-pos speed - - - - Playback speed in thousandths of a percent. 100000 = normal speed. - - - - - - pitch-flag - - - - Controls whether audio pitch changes with speed or not. 0 = no, - 1 = yes. - - - - + + + + + pid + + + An integer value, giving the process ID of the process + originating the command. + + + + + serial + + + An integer value, giving the serial number of the command. + This can be any 32 bit positive integer value, but + must be unique within the scope of the + process originating the command! + + + + + + cut-name + + + The cut name of the target cut. + + + + + card-num + + + The number of the audio card to use. + + + + + port-num + + + The number of the port on the audio card to use. + + + + + start-pos + + + The start position, in milliseconds from absolute start of the + audio PCM data. + + + + + end-pos + + + The position at which to end play-out, in milliseconds from + absolute start of the audio PCM data. + + + + + speed + + + The speed of the play-out, with 100000 + indicating 100%. + + + + + + + <command>Play Position</command> + + Position the playback cursor of a currently active audio play-out. + + + + PP + pid + serial + position + + + + + pid + + + Integer value. Should be the same value as that used in the prior + + Start Playback + + operation. + + + + + serial + + + Integer value. Should be the same value as that used in the prior + + Start Playback + + operation. + + + + + + position + + + + Position in file to play from, in milliseconds from absolute + start pf the audio PCM data. + + + + + + + + <command>Pause Playback</command> + + Pause playback of the specified play session, while maintaining + the specified session. + + + + PE + pid + serial + + + + + pid + + + Integer value. Should be the same value as that used in the prior + + Start Playback + + operation. + + + + + serial + + + Integer value. Should be the same value as that used in the prior + + Start Playback + + operation. + + + + + + + + <command>Resume Playback</command> + + Resume playback of the specified play session from the current + playback cursor position. + + + + PR + pid + serial + + + + + pid + + + Integer value. Should be the same value as that used in the prior + + Start Playback + + operation. + + + + + serial + + + Integer value. Should be the same value as that used in the prior + + Start Playback + + operation. + + + + + + + + <command>Stop Playback</command> + + Stop playback of the specified play session, closing the associated + audio file and destroying the specified session. + + + + SP + pid + serial + + + + + pid + + + Integer value. Should be the same value as that used in the prior + + Start Playback + + operation. + + + + + serial + + + Integer value. Should be the same value as that used in the prior + + Start Playback + + operation. + + + + + + + + <command>Set Output Volume</command> + + Set the volume of an active play-out. + + + + OV + pid + serial + level + + + + + pid + + + Integer value. Should be the same value as that used in the prior + + Start Playback + + operation. + + + + + serial + + + Integer value. Should be the same value as that used in the prior + + Start Playback + + operation. + + + + + + level + + + + The level, in hundreths of a dB. + + + + + + + + <command>Fade Output Volume</command> + + Transition the volume of an active audio play-out over time. + + + + FV + pid + serial + level + length + + + + + pid + + + Integer value. Should be the same value as that used in the prior + + Start Playback + + operation. + + + + + serial + + + Integer value. Should be the same value as that used in the prior + + Start Playback + + operation. + + + + + + level + + + + The level, in hundreths of a dB. + + + + + + length + + + + The length of the transition, in milliseconds. + + + + + - - <command>Stop Playback</command> - - Stop playback of the specified playback interface. - - - SP conn-handle! - - - - - conn-handle - - - - The connection handle of the playback event, from the - Load Playback call. - - - - - + + Responses + + <command>Playback Stopped</command> + + Indicates that the specified play-back session has terminated. + + + + SP + pid + serial + + + + + pid + + + Integer value. The same value as that used in the prior + + Start Playback + + operation. + + + + + serial + + + Integer value. The same value as that used in the prior + + Start Playback + + operation. + + + + + - - <command>Timescaling Support</command> - - Query CAE if card-num supports timescaling. - - - TS card-num! - - - - - card-num - - - - The number of the audio adapter to query. - - - - - - Returns: TS - card-num - +|-! - + + <command>Play Position</command> + + Indicates the current location of the play cursor. + + + + PP + pid + serial + position + + + + + pid + + + Integer value. The same value as that used in the prior + + Start Playback + + operation. + + + + + serial + + + Integer value. The same value as that used in the prior + + Start Playback + + operation. + + + + + + position + + + + Current position in file of the play cursor,in milliseconds + from absolute start pf the audio PCM data. + + + + + - + Record Operations - - <command>Load Recording</command> - - Prepare an audio interface to capture an audio file. - - - LR - card-num - port-num - coding - channels - samp-rate - bit-rate - name! - - - - + + Commands + + <command>Cue Recording</command> + + Cue recording to an audio file, while also creating an + ongoing session that can be operated upon with the remainder of the + commands documented in this section. + + + + LR + pid + serial + cut-name card-num - - - - The number of the audio adapter to query. - - - - - port-num - - - - The port number to use. This is relative to the audio adapter - selected. - - - - - coding - - - - 0 = PCM16, 1 = MPEG Layer 1, 2 = MPEG Layer 2, 4 = PCM24 - - - - - channels - - - - 1 = Mono, 2 = Stereo - - - - - - samp-rate - - - - Sample Rate in samples/sec. 32000, 44100 or 48000 supported. - - - - - - bit-rate - - - - MPEG Bit Rate. For PCM, this should be zero. - - - - - - name - - - - The base name of a file in the audio storage filesystem. If the - file already exists, it will be overwritten, otherwise it will be - created. - - - - - + + + + + pid + + + An integer value, giving the process ID of the process + originating the command. + + + + + serial + + + An integer value, giving the serial number of the command. + This can be any 32 bit positive integer value, but + must be unique within the scope of the + process originating the command! + + + + + + cut-name + + + + The cut name of the target cut. If the cut audio already exists, + it will be overwritten with a new file containing a WAV header, + but no PCM data. + + + + + + card-num + + + + The number of the audio card. + + + + + + port-num + + + + The port number to use. This is relative to the audio adapter + selected. + + + + + + coding + + + + 0 = PCM16, 1 = MPEG Layer I, 2 = MPEG Layer II, 4 = PCM24 + + + + + + channels + + + + 1 = Mono, 2 = Stereo + + + + + + samp-rate + + + + Sample Rate in samples/sec. 32000, 44100 or 48000 supported. + + + + + + bit-rate + + + + MPEG Bit Rate. For PCM, this should be zero. + + + + + - - <command>Unload Recording</command> - - Free an audio capture interface. - - - UR card-num - stream-num! - - - - - card-num - - - - The number of the audio adapter to use. - - - - - - stream-num - - - - The stream number to use. This is relative to the audio adapter - selected. - - - - - - Returns: UR - card-num - stream-num - len! - - - - - len - - - - Length of recording, in mS. - - - - - - - - <command>Record</command> - - Record a loaded file. - - - RD card-num - stream-num - length - threshold! - - - - - card-num - - - - The number of the audio adapter to use. - - - - - - stream-num - - - - The stream number to use. This is relative to the audio adapter - selected. - - - - - + + <command>Start Recording</command> + + Start recording --i.e. sending PCM data to a file. The recording must + be in a cued state (see + ). + To cue and start a recording in a single operation, see + . + + + + RD + pid + serial length - - - - Length of time to record in milliseconds. If zero, record until - told to stop. - - - - - threshold - - - - Threshold of audio detected at which to start recording, in - 1/100 dBFs. If '0', start immediately. - - - - - - Returns: When recording actually begins, a Record Start (RS) - confirmation will be echoed back. If record time expires a Stop Record - (SR) confirmation will be echoed back. - - + + + + + pid + + + Integer value. The same value as that used in the prior + + Cue Recording + + operation. + + + + + serial + + + Integer value. The same value as that used in the prior + + Cue Recording + + operation. + + + + + + length + + + + Length of time to record in milliseconds. If zero, record until + told to stop. + + + + + + threshold + + + + Threshold of audio detected at which to start recording, in + 1/100 dBFs. If '0', start immediately. + + + + + - - <command>Stop Recording</command> - - Stop recording of the specified record interface. - - - SR card-num - stream-num! - - - - + + <command>Cue and Start Recording</command> + + Cue and Start recording to a file in a single operation. + + + + RC + pid + serial + cut-name card-num - - - - The number of the audio adapter. - - - - - - stream-num - - - - The stream number. - - - - - - - - <command>Record Start</command> (Receive Only) - - Receive-only signal to indicate recording has actually - started (as with a VOX event, where actual recording may begin some - time after the interface is placed into record). - - - RS card-num - stream-num! - - - - - card-num - - - - The number of the audio adapter to use. - - - - - - stream-num - - - - The stream number to use. This is relative to the audio adapter - selected. - - - - - - - - - Mixer Operations - - <command>Set Input Volume</command> - - Set the volume of an input stream. - - - IV card-num - stream-num - level! - - - - - card-num - - - - The number of the audio adapter to use. - - - - - - stream-num - - - - The stream number to use. This is relative to the audio adapter - selected. - - - - - - level - - - - The level, in hundreths of a dB. - - - - - - - - <command>Set Output Port</command> - - Configure an output stream to use a particular output port. - - - This will cause the stream-num output volume - control feeding the port-num port to be set - to the level given by level, while all other - output_volume controls for that stream to be muted --e.g. set to - -100 dB. - - - OP card-num - stream-num - port-num - level! - - - - - card-num - - - - The number of the audio adapter to use. - - - - - - stream-num - - - - The stream number to use. This is relative to the audio adapter - selected. - - - - - port-num - - - - The port number to use. This is relative to the audio adapter - selected. - - - - - - level - - - - The level, in hundreths of a dB. - - - - - - - - <command>Set Output Volume</command> - - Set the volume of an output stream. - - - OV card-num - stream-num - port-num - level! - - - - - card-num - - - - The number of the audio adapter to use. - - - - - - stream-num - - - - The stream number to use. This is relative to the audio adapter - selected. - - - - - - port-num - - - - The port number to use. This is relative to the audio adapter - selected. If a value less than 0 is - provided, then all output ports for - stream-num will have their volume - controls set to level. - - - - - - level - - - - The level, in hundreths of a dB. - - - - - - - - <command>Fade Output Volume</command> - - Transition the volume of an output stream over time. - - - FV card-num - stream-num - port-num - level - length! - - - - - card-num - - - - The number of the audio adapter to use. - - - - - - stream-num - - - - The stream number to use. This is relative to the audio adapter - selected. - - - - - - port-num - - - - The port number to use. This is relative to the audio adapter - selected. - - - - - - level - - - - The level, in hundreths of a dB. - - - - - + coding + channels length - - - - The length of the transition, in milliseconds. - - - - + threshold + + + + + pid + + + An integer value, giving the process ID of the process + originating the command. + + + + + serial + + + An integer value, giving the serial number of the command. + This can be any 32 bit positive integer value, but + must be unique within the scope of the + process originating the command! + + + + + + cut-name + + + + The cut name of the target cut. If the cut audio already exists, + it will be overwritten. + + + + + + card-num + + + + The number of the audio card. + + + + + + port-num + + + + The port number to use. This is relative to the audio adapter + selected. + + + + + + coding + + + + 0 = PCM16, 1 = MPEG Layer I, 2 = MPEG Layer II, 4 = PCM24 + + + + + + channels + + + + 1 = Mono, 2 = Stereo + + + + + + samp-rate + + + + Sample Rate in samples/sec. 32000, 44100 or 48000 supported. + + + + + + bit-rate + + + + MPEG Bit Rate. For PCM, this should be zero. + + + + + + length + + + + Length of time to record in milliseconds. If zero, record until + told to stop. + + + + + + threshold + + + + Threshold of audio detected at which to start recording, in + 1/100 dBFs. If '0', start immediately. + + + + + + + + <command>Stop Recording</command> + + Stop recording of the specified record interface. + + + + SR + pid + serial + + + + + pid + + + Integer value. The same value as that used in the prior + + Cue Recording + + or + + Cue and Start Recording + + operation. + + + + + serial + + + Integer value. The same value as that used in the prior + + Cue Recording + + or + + Cue and Start Recording + + operation. + + + + + - - <command>Set Input Level</command> - - Set the gain level of an input port. - - - IL card-num - port-num - level! - - - - - card-num - - - - The number of the audio adapter to use. - - - - - - stream-num - - - - The port number to use. This is relative to the audio adapter - selected. - - - - - - level - - - - The level, in hundreths of a dB. - - - - + + Responses + + <command>Record State Changed</command> + + Indicate start or stop of specified recording. + (With a VOX event, the actual recording may begin some + time after the interface is placed into record). + + + + RS + pid + serial + state + + + + + pid + + + Integer value. The same value as that used in the prior + + Cue Recording + + or + + Cue and Start Recording + + operation. + + + + + serial + + + Integer value. The same value as that used in the prior + + Cue Recording + + or + + Cue and Start Recording + + operation. + + + + + + state + + + + 1 = Record has started, 0 = Record has stopped. + + + + + - - - <command>Set Output Level</command> - - Set the gain level of an output port. - - - OL card-num - port-num - level! - - - - + + + + Mixer Operations + + Commands + + <command>Get Input Status</command> + + Request the status of an input port. + + + + IS + pid + serial card-num - - - - The number of the audio adapter to use. - - - - - port-num - - - - The port number to use. This is relative to the audio adapter - selected. - - - - - - level - - - - The level, in hundreths of a dB. - - - - - + + + + + + card-num + + + + The number of the audio adapter to use. + + + + + + port-num + + + + The port number to use. This is relative to the audio adapter + selected. + + + + + - - <command>Set Input Mode</command> - - Set the mode of an input stream. - - - IM card-num - stream-num - mode! - - - - + + <command>Set Audio Passthrough Level</command> + + Set the gain of an audio passthrough path. + + + + AL + pid + serial card-num - - - - The number of the audio adapter to use. - - - - - - port-num - - - - The stream number to use. This is relative to the audio adapter - selected. - - - - - - mode - - - - The mode, as follows: - - - - 0 - - - - Normal - - - - - - 1 - - - - Swap left and right channels - - - - - - 2 - - - - Left audio on both channels - - - - - - 3 - - - - Right audio on both channels - - - - - - - - - - - - <command>Set Output Mode</command> - - Set the mode of an output stream. - - - OM card-num - stream-num - mode! - - - - - card-num - - - - The number of the audio adapter to use. - - - - - - stream-num - - - - The stream number to use. This is relative to the audio adapter - selected. - - - - - - mode - - - - The mode, as follows: - - - - 0 - - - - Normal - - - - - - 1 - - - - Swap left and right channels - - - - - - 2 - - - - Left audio on both channels - - - - - - 3 - - - - Right audio on both channels - - - - - - - - - - - - <command>Set Input Vox Level</command> - - Set the VOX threshold level of an input stream. - - - IX card-num - stream-num - level! - - - - - card-num - - - - The number of the audio adapter to use. - - - - - - port-num - - - - The stream number to use. This is relative to the audio adapter - selected. - - - - - - level - - - - The level, in hundreths of a dB. - - - - - - - - <command>Set Input Type</command> - - Set the signal type of an input port. - - - IT card-num - port-num - type! - - - - - card-num - - - - The number of the audio adapter to use. - - - - - - port-num - - - - The port number to use. This is relative to the audio adapter - selected. - - - - - - type - - - - The mode, as follows: - - - - 0 - - - - Analog - - - - - - 1 - - - - AES3 Digital - - - - - - - - - - - - <command>Get Input Status</command> - - Request the status of an input port. - - - IS card-num - port-num! - - - - - card-num - - - - The number of the audio adapter to use. - - - - - - port-num - - - - The port number to use. This is relative to the audio adapter - selected. - - - - - - Returns: IS - card-num - port-num - status! - - - - - status - - - - The status, as follows: - - - - 0 - - - - OK - - - - - - 1 - - - - No Sync - - - - - - - - - - - - <command>Set Audio Passthrough Level</command> - - Set the gain of an audio passthrough path. - - - AL card-num - input-num - output-num - level! - - - - - card-num - - - - The number of the audio adapter to use. - - - - - input-num - - - - The input number to use. This is relative to the audio adapter - selected. - - - - - output-num - - - - The output number to use. This is relative to the audio adapter - selected. - - - - - level - - - - The level, in hundreths of a dB. - - - - + + + + + + card-num + + + + The number of the audio adapter to use. + + + + + + input-num + + + + The input number to use. This is relative to the audio adapter + selected. + + + + + + output-num + + + + The output number to use. This is relative to the audio adapter + selected. + + + + + + level + + + + The level, in hundreths of a dB. + + + + + - - <command>Set Clock Source</command> - - Set source of an audio adapter's sample clock. Relevant only for - cards that feature AES3 inputs. - - - CS card-num - input-num! - - - - - + + Responses + + <command>Input Status</command> + + Report the status of an input port. + + + + IS card-num - - - - The number of the audio adapter to use. - - - - - - input-num - - - - The input number to use. This is relative to the audio adapter - selected. - - - - + port-num + + + + + + card-num + + + + Audio card number. + + + + + + port-num + + + + Audio port number. + + + + + + status + + + + The status, as follows: + + + + 0 + + + + OK + + + + + + 1 + + + + No Sync + + + + + + + + + + - + External Operations <command>Open RTP Capture Channel</command>