Recording Search API
The Recording Search application API makes it possible to list recordings spans and get information about their containers and tracks.
Overview
Identification
gdbus introspect --system
--dest=com.axis.RecordingSearch1
--object-path /com/axis/RecordingSearch1
Check that the root node of the returned introspection data contains the
interface com.axis.RecordingSearch1.Search1.
The D-Bus error org.freedesktop.DBus.Error.ServiceUnknown will be
returned if the service is not available.
D-Bus Names
D-Bus Service: com.axis.RecordingSearch1
Main D-Bus object: /com/axis/RecordingSearch1
D-Bus interface: com.axis.RecordingSearch1.Search1
Use Cases
Get all recording spans
A client wants to get all new recording spans since a saved timestamp of a recording.
Use Search interface for getting all spans of a recording group
All code listings are examples. See references for detailed description of each API command.
- The application lists the recording spans newer than the saved
timestamp for the recording group with:
gdbus call --system--dest=com.axis.RecordingSearch1--object-path /com/axis/RecordingSearch1--method com.axis.RecordingSearch1.Search1.ListSpans'SD_DISK' 'recgroup1' '2023-10-18T00:00:00Z' '2023-10-19T00:00:00Z''' '' 500
Get recording containers and tracks
A client wants to list the containers and tracks of a recording.
Use Search interface for getting the containers and tracks of a recording span
-
The application lists the containers and tracks of a recording span with:
gdbus call --system--dest=com.axis.RecordingSearch1--object-path /com/axis/RecordingSearch1--method com.axis.RecordingSearch1.Search1.GetSpanAttributes'SD_DISK' 'recgroup1:20231018062954053'Example response for recording span with separate containers for video and audio:
('2023-10-18T06:29:54.053Z', '2023-10-18T06:30:26.286Z', 'event1',{'a1': ('cmaf', [{'channel': <'1'>, 'codec': <'mp4a.40.2'>,'bitrate': <32000>, 'samplerate': <48000>}]),'v1': ('cmaf', [{'channel': <'1'>, 'codec': <'avc1.640028'>,'framerate': <'30:1'>, 'width': <1920>,'height': <1080>}])})Example response for recording span with video and audio muxed in one container:
('2023-10-18T06:29:54.053Z', '2023-10-18T06:30:26.286Z', 'event1',{'mux': ('matroska',[{'channel': <'1'>, 'codec': <'avc1.640028'>, 'framerate': <'30:1'>,'width': <1920>, 'height': <1080>},{'channel': <'1'>, 'codec': <'mp4a.40.2'>, 'bitrate': <32000>,'samplerate': <48000>}])})
Get some recording segments
A client wants to list recording segments to produce a playlist for a part of a recording.
Use Search interface for listing recording segments of a recording group
- The application lists the recording segments of a recording group
for a time interval with:
gdbus call --system--dest=com.axis.RecordingSearch1--object-path /com/axis/RecordingSearch1--method com.axis.RecordingSearch1.Search1.ListSegments'SD_DISK' 'recgroup1' '2023-10-18T06:30:00Z' '2023-10-18T06:35:00Z'500
API Definition
com.axis.RecordingSearch1.Search1
This interface provides methods for retrieving information about recording spans and their segments.
The ListSpans method
ListSpans (in s storage_id,
in s group_id,
in s start_time,
in s stop_time,
in s video_channel,
in s audio_channel,
in u max_results,
out a(ssss) spans);
Returns a list of recording spans. All times are in ISO 8601 format.
Input parameters:
storage_id: The storage to search.group_id: Match recordings belonging to this recording group if set.start_time: Match recordings at or after this time if set.stop_time: Match recordings before this time if set.video_channel: Match recordings containing this video channel if set.audio_channel: Match recordings containing this audio channel if set.max_results: The maximum number of results to return. There is a hardcoded limit of 1000 results.
Output parameters:
spans: A list of structs containing (group_id, span_id, start_time, stop_time).group_id: The ID of the recording group.span_id: The ID of the recording span.start_time: The start time of the recording span.stop_time: The stop time of the recording span.
Possible D-Bus errors:
com.axis.RecordingSearch1.Error.Generalcom.axis.RecordingSearch1.Error.InvalidArgumentcom.axis.RecordingSearch1.Error.Unauthorized
The GetSpanAttributes method
GetSpanAttributes (in s storage_id,
in s span_id,
out s start_time,
out s stop_time,
out s event_id,
out a{s(saa{sv})} containers);
Returns the attributes of the recording span. All times are in ISO 8601 format. The containers is a dictionary with the container ID as key and a struct with the container type and a list of tracks as value.
Video track attributes:
channel: The video channel identifier (string).codec: The video codec according to RFC 6381 (string).framerate: The video framerate in "frames:seconds" (string).width: The video width in pixels (int32).height: The video height in pixels (int32).
Audio track attributes:
channel: The audio channel identifier (string).codec: The audio codec according to RFC 6381 (string).bitrate: The audio bitrate in bits per second (int32).samplerate: The audio samplerate in hertz (int32).
Input parameters:
storage_id: The storage the recording span is stored on.span_id: The ID of the recording span.
Output parameters:
start_time: The start time of the recording span.stop_time: The stop time of the recording span.event_id: The event ID of the recording span.containers: A dictionary with the containers and their tracks.
Possible D-Bus errors:
com.axis.RecordingSearch1.Error.Generalcom.axis.RecordingSearch1.Error.InvalidArgumentcom.axis.RecordingSearch1.Error.Unauthorized
The ListSegments method
ListSegments (in s storage_id,
in s group_id,
in s start_time,
in s stop_time,
in u max_results,
out a(sss) segments);
Returns a list of recording segments. All times are in ISO 8601 format.
Input parameters:
storage_id: The storage to search.group_id: Match segments belonging to this recording group.start_time: Match segments at or after this time if set.stop_time: Match segments before this time if set.max_results: The maximum number of results to return. There is a hardcoded limit of 1000 results.
Output parameters:
segments: A list of structs containing (segment_id, start_time, stop_time).segment_id: The ID of the segment.start_time: The start time of the segment.stop_time: The stop time of the segment.
Possible D-Bus errors:
com.axis.RecordingSearch1.Error.Generalcom.axis.RecordingSearch1.Error.InvalidArgumentcom.axis.RecordingSearch1.Error.Unauthorized