1. Accessing Media via HTTP(S)¶
NexLog recorders support several methods of accessing media via a programmable API. This section describes accessing media via an HTTP interface. Media can be retrieved either as a single record or as a time range from a list of physical channels. In order to retrieve a single media file, the user must have information about the call that’s being pulled. This can either be the CallGuid or some other metadata associated with another system. For example, if a call was annotated with a unique value from an external source using the Eventide NexLog Metadata Feeds protocol then the media could be retrieved using that known value.
The HTTP protocol requires Basic web authentication. Credentials can be sent in the URL or in response to an Authentication request. The recorder can also be configured to support or require SSL (See NexLog User Manual). The authenticating user must have the appropriate channel/resource permissions to access the requested recordings. By default, an admin user will have permissions to all channels/resources. See the NexLog User Manual for information on managing user permissions.
Unless otherwise specified, Media is returned as WAV files containing linear PCM 16-bit signed samples with a sampling rate of 8000 hertz. If requesting RTP streaming the recommendation is to request 8-bit Mulaw compression by adding comp=1 to the GET request.
Media is requested via the URL, <PROTOCOL><ADDRESS>/agent/retrieveMedia.py
The request must contain a valid URL argument set. Note that the URI arguments must be properly encoded. Examples of valid URLs can be found here
- GET /agent/retrieveMedia.py¶
1.1. URL Parameters - General¶
c - Specify which channel(s) will be used in the command in the form c=<channel1>[,<channel2>,…]
comp - Audio compression. For RTP streaming this should always be comp=1 for 8-bit G.711 Mulaw. For WAV file download do not specify the compression type to download the default uncompressed 16-bit linear audio
ctw - Send audio back as a WAV file. Including ctw=1 will send the HTTP Content-Type header “audio/x-wav” for the client to play the audio as a WAV. The header “application/octet-stream” will present the audio as a downloadable file
d - Enable debug. d=1 enables output to the debug log which is accessible at <PROTOCOL><ADDRESS>/downloads/debug.txt
k - Use a stored metadata key to find a specific recording. This must be used with the value command v to specify a unique key-value pair to identify a single recording
l - Local playback. Play through the front panel speaker of the recorder
m - Mono audio output. m=1 should always be set for RTP streaming
q - Run the database query, but do not send audio
t1 - The start time in UNIX format for either the dataset window or the playback start time
t1iso - The start time in ISO format for either the dataset window or the playback start time
t2 - The end time in UNIX format for either the dataset window or the playback end time
t2iso - The end time in ISO format for either the dataset window or the playback end time
v - Use a stored metadata value to find a specific recording. This must be used with the key command k to specify a unique key-value pair to identify a single recording
w - Wait for completion before sending to client,
0(default),1
1.2. URL parameters - RTP specific¶
buffer - Number of seconds to stream ahead of the current time. For example, buffer=1 will send one second of RTP data as quickly as possible and then subsequent RTP packets will be sent at the same speed that they were recorded.
cached - Start playback from a cached dataset. Playback should start in near real-time. This should be used after the dataset is created using the prepare and session commands.
clearSession - Stop playback and free the prepared dataset.
multicast - Send RTP to multicast destination. Used with the rtp command to specify the IP address and port.
noWait - Run the request in the background and return immediately. Making requests with noWait=1 does not provide feedback as to the success or failure of the requested action. This can be used when starting streaming so that a TCP connection does not have to remain open during the duration of the audio playback.
payload_ms - Specify the frame size of the RTP audio packets. This command should be used for any receiving party that requires a specific frame size for incoming RTP audio. Sending the command payload_ms=20 with the streaming request will result in the recorder sending 20 milliseconds of audio in each RTP packet. The default frame size is 60ms.
prepare - Prepare a dataset for playback. The preparation may take many seconds to complete when long periods of time or many channels are requested. Once the dataset is prepared, subsequent playback requests using the cached dataset should start immediately. A dataset stays prepared until a clearSession=1 is called for that session or 30 days elapse since the creation of the dataset. The session may only have one dataset prepared at a time. A channel, playback start time, and stop time must be specified in the playback command URL. The channel argument will filter playback from within the prepared dataset. The start and stop time will be used to start and stop playback within the prepared dataset.
rtp - Comma separated list of destination address and port to stream RTP. Defined as rtp=<address>:<port>[,…]
session - Used to identify a requesting client such that a dataset (see ‘prepare’) and playback can be referenced in corresponding calls. The session is defined by the calling process. Sessions can be re-used. A session should not have more than one stream active at a time. Note, if more than one stream is active for a session it won’t be possible to stop playback. Example, session=cwp1
speed - Controls the speed of playback. This is a value from -100 to 100 with 0 being normal speed. Negative numbers are slower and positive numbers are faster. Example, speed=-50
stopPlayback - Stops the current playback for the specified session. Example, stopPlayback=1.
1.3. URL Examples¶
The HTTP GET request must contain a valid URL argument set. Note that the URI arguments must be properly encoded. Examples of valid URLs are as follows.
1.3.1. Retrieve media with a matching value for a metadata field¶
Example:
GET /agent/retrieveMedia.py?k=MyCallId&v=111222333 HTTP/1.1 Host: 192.168.1.1 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) Accept: */* Authorization: Basic RXZlbnRpZGU6MTIzNDU=
Description:
Stream the WAV file for a call record containing the value of 111222333 for the metadata field named MyCallId. The metadata field may be a field created by the recorder during normal recording operations (SIP CALLID), or a custom field entered by a 3rd party and populated from an external source. Note that the specified key column name should be indexed for best performance.
1.3.2. Retrieve media by matching an Eventide CallGuid¶
Example:
GET /agent/retrieveMedia.py?v=ATG83KsaIoJ91NaW HTTP/1.1 Host: 192.168.1.1 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) Accept: */* Authorization: Basic RXZlbnRpZGU6MTIzNDU=
Description:
Stream the WAV file for the call with CallGuid value ATG83KsaIoJ91NaW. The CallGuid must be determined using a different API (ODBC, SOAP, REST).
1.3.3. Retrieve media by matching an Eventide ID¶
Example:
GET /agent/retrieveMedia.py?k=id&v=1 HTTP/1.1 Host: 192.168.1.1 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) Accept: */* Authorization: Basic RXZlbnRpZGU6MTIzNDU=
Description:
Stream the WAV file that matches ID equal to 1. The recorder has a sequenced ID field. The first call on the recorder will have id=1. Note that when the recorder runs out of space it will remove the oldest call ID’s to make room for new ID’s.
1.3.4. Retrieve media via complex date and channel based criteria¶
This example shows media retrieval based on a start time and an end time and a list of channels. Times are specified as either an ISO date time (t1iso, t2iso) string or a UNIX date time (t1, t2).
Example:
GET /agent/retrieveMedia.py?c=1,2&t1iso=20121023T040200&t2iso=20121023T050200 HTTP/1.1 Host: 192.168.1.1 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) Accept: */* Authorization: Basic RXZlbnRpZGU6MTIzNDU=
Description:
Create a WAV file with recordings between two dates on physical channels 1 and 2 where the recordings play in real-time. Silence will be included in the file. Note that only authorized recordings will be included in the file.
1.3.5. Retrieve media packaged as RTP¶
By default, the media is returned to the requester in the resultant payload of the HTTP GET command. The API can also request that the resulting media is streamed from the recorder to specified addresses. The stream consists of Real-Time Transport Protocol (RTP) packetized media sent over the UDP protocol.
When RTP mode is specified in the HTTP GET request via the rtp parameter, the RTP audio will be streamed to the specified addresses, and status text will be returned from the GET request. Each status text is separated by a newline character. The current playback time is sent out at least one time per second for a play request that is not backgrounded (without noWait=1). Status messages that begin with “Success.” Indicate normal operation. Messages that begin with “Warning.” Indicate that the controlling program might need to handle a problem. Messages that begin with “Error.” Indicate that there is a problem that might require the attention of the end user. Possible status messages include, but are not limited to,
Success. Command sent. - This will be seen when noWait=1 is sent. This should only be used on playback of streaming RTP when the HTTP GET command cannot be held open until the end of the audio playback.
Success. Streaming started. - This text is sent as RTP streaming starts and is followed by update messages (see “Sent=).
Sent=(seconds from beginning of file) - This update is sent in the form “Sent= 54.375” every 0.125 seconds during the duration of RTP streaming unless the play command was started with noWait=1.
Streaming complete. Sent bytes=(number of bytes sent) - This is the final message during RTP streaming when the playback reaches the end of the time window specified.
Warning. Failed to find stream. - This indicates that the recorder is not able to find the named session. Either the named session has not been created, has already been removed with clearSession=1, or the session has expired 30 days after creation.
Success. Streaming stopped. - This message is returned when RTP streaming is in progress and the stopPlayback=1 command is sent.
Success. Cache removed. - This message is returned when the clearSession=1 command is sent and the named session currently exists.
Warning. Cache not found. - This message is returned when the clearSession=1 command is sent and the named session does not exist or has already been cleared.
Success. Dataset ready. - This message is returned when running a prepare=1 command to set up the dataset window with start time, stop time, and channels queried from the database and saved in a cache file for faster access.
Error. Database connection failed for user, (username). - The user credentials passed with the HTTP GET request in the authentication header must have rights to query the database or this error will be generated.
Error. Messaging failed for user, (username). - The messaging system internal to the recorder returned an error for the authenticated user.
Error. Init failed. - Internal error indicating that the streaming process failed to initialize. Possible reasons include a failure to connect to the internal media server or database.
Error. Failed to find record for key=(key) value=(value)”. The record may not exist or you may not have permission to access it. - No records were returned when the database was queried for the given key and value pair.
Error. Permission to access this recording has been denied. - The user permissions on the recorder did not allow access to the specified recording with the credentials that were passed in with the authentication header of the HTTP GET command.
Error. Media type not supported. - This is likely due to attempting to stream a screen capture recording.
Error. Failed to find database cache file. - This error can occur if an attempt is made to play from a session that has been destroyed or never created.
Error. Media not processed. - No audio was generated for the request. This could indicate invalid time parameters being sent.
1.3.5.1. Streaming notes¶
The HTTP GET command must be kept open for the duration of the request unless processing is backgrounded with noWait=1. If it is closed prematurely then streaming will stop.
The amount of time between the initial request and the start of RTP streaming is not guaranteed. To achieve synchronization between various media sources it is necessary to process the status command from the HTTP GET request. Using the prepare=1 and cached=1 commands will make the playback timing much more predictable.
Format <PROTOCOL><ADDRESS>/agent/retrieveMedia.py?c=<channel numbers>&t1iso=<ISO formatted time>&t2iso=<ISO formatted time>&rtp=<DESTINATION_ADDRESS>:<DESTINATION_PORT>&buffer=<seconds to buffer>
Description: Start streaming recordings between two dates on physical channels 1 and 2. Silence will be included in the file to create an accurate representation of events. The recordings will be streamed as RTP to 192.168.1.1:6777. The data will be sent out in real-time without any buffered audio.
1.3.5.2. Example session to create a dataset and play from it¶
Initialize the dataset named sess1 and include channels 1-6 from midnight 25 October 2019 to 23:59:59 on 25 October 2019. http://192.168.1.1/agent/retrieveMedia.py?c=1,2,3,4,5,6&comp=1&m=1&prepare=1&session=sess1&t1iso=20191025T000000&t2iso=20191025T235959 Success. Dataset ready.
Play channels 1-6 mixed together from times 20:08:00 to 20:08:03.
Success. Streaming started.
Sent= 0.25
Sent= 0.375
Sent= 0.5
Sent= 0.625
Sent= 0.75
Sent= 0.875
Sent= 1.0
Sent= 1.125
Sent= 1.25
Sent= 1.375
Sent= 1.5
Sent= 1.625
Sent= 1.75
Sent= 1.875
Sent= 2.0
Streaming complete. Sent bytes=16442
Attempting to stop playback of a session that has already stopped.
http://192.168.1.1/agent/retrieveMedia.py?session=sess1&stopPlayback=1
Warning. Failed to find stream.
Play only channel 1 from times 20:08:00 to 20:08:01.
Success. Streaming started.
Sent= 0.25
Sent= 0.375
Sent= 0.5
Sent= 0.625
Sent= 0.75
Sent= 0.875
Sent= 1.0
Sent= 1.125
Sent= 1.25
Sent= 1.375
Sent= 1.5
Sent= 1.625
Sent= 1.75
Sent= 1.875
Sent= 2.0
Sent= 2.05525
Streaming complete. Sent bytes=16442
Delete the session.
http://192.168.1.1/agent/retrieveMedia.py?clearSession=1&session=sess1
Success. Cache removed.