Fred Gleason fredg@paravelsystems.com 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. This document describes the IPC mechanisms by which other components of Rivendell can interact with CAE. 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: 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. 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). 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. 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 [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. 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 port-num start-pos end-pos speed 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%. 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. 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. 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. 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. 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. 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. 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. 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. 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 port-num coding channels 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. 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 threshold 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. Cue and Start recording to a file in a single operation. RC pid serial cut-name card-num port-num coding channels length 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. 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. 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. Request the status of an input port. IS pid serial 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. Set the gain of an audio passthrough path. AL pid serial 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. Report the status of an input port. IS card-num port-num card-num Audio card number. port-num Audio port number. status The status, as follows: 0 OK 1 No Sync Open an RTP channel for audio capture. CO card-num port-num udp-port samp-rate channels! card-num The number of the audio adapter to use. udp-port The port number on the remote system to which to send RTP packets. samp-rate The requested sample rate. channels The requested number of channels. Returns: CO card-num port-num udp-port samp-rate chans pkt-size! pkt-size The number of bytes to send per UDP packet. The actual sample rate and number of channels may be different from those requested; clients must be prepared to detect and deal with this possibility! Set UDP port to which to send meter update messages for the specified card(s). ME udp-port card0 ..! udp-port UDP port number. card0 Audio card number for which to send updates. The following messages are sent by CAE to indicate current status and audio levels. They are sent to the UDP port requested by the Meter Enable ['ME'] command. Send current meter level of output stream ML type card-num port-num left-lvl right-lvl! type Type of meter. I Input O Output card-num The number of the audio adapter to use. port-num The port number on the audio adapter. left-lvl Left channel level, in 100ths of dBFS. right-lvl Right channel level, in 100ths of dBFS. Send current meter level of output stream MO card-num port-num left-lvl right-lvl! card-num The number of the audio adapter to use. port-num The port number on the audio adapter. left-lvl Left channel level, in 100ths of dBFS. right-lvl Right channel level, in 100ths of dBFS. Output play position. MP card-num stream-num pos! card-num The number of the audio adapter to use. stream-num The stream number on the audio adapter. pos The play position in mS. The current output stream transport status. MS card-num port-num stream-num status! card-num The number of the audio adapter to use. port-num The port number on the audio adapter. stream-num The stream number on the audio adapter. status Current transport status. 0 Stopped 1 Playing