Media clip API

Description

The Media clip API gives applications and users the ability to play media clips controlled from the user interface or external applications. The supported media type is audio.

The API supports the following functionality:

Play and stop a media clip.
Upload a media clip to the Axis product.
Download a media clip from the Axis product (for backup or editing purposes).

The API consists of two CGIs; mediaclip.cgi that allows operators to manage media clips and playclip.cgi that allows viewers to play media clips. A media clip is an audio clip that is stored in the camera and could be played with the camera's speaker.

The following audio clip formats are supported:

au format, with audio encoded in µ-law or PCM.
wav format, with audio encoded in µ-law, mp3 or PCM .
mp3 format.
opus format
vorbis format (e.g. Ogg Vorbis)

The parameter Properties.AudioClip.Format specifies audio formats available on the Axis product.

Prerequisites

Identification

Property: Properties.API.HTTP.Version=3
Property: Properties.Audio.Audio=yes
Property: Properties.Audio.Source.A#.Output=yes

Further capabilities may be specified in the Properties.AudioClip parameter group, see AudioClip properties parameters.

Firmware: 5.40 and later
Product category: For playing, an audio output is required (speaker or line out).

Dependencies

The parameters (see Parameters) are managed through the parameter management CGI param.cgi. This function is device specific, which means that transmit.cgi might not be used while playing a media clip.

Please note that this API no longer support the option to record media clips. Instead, see Edge Storage API for information and examples on how to make recordings with your device.

Common examples

Play a media clip

Audio clips can be played by using one of the following methods:

Play clip 0 (MediaClip.M0).

http://<servername>/axis-cgi/mediaclip.cgi?action=play&clip=0

Play clip 0 (MediaClip.M0) at audiodeviceid 0 and audiooutputid 0.

http://<servername>/axis-cgi/mediaclip.cgi?action=play&clip=0&audiodeviceid=0&audiooutputid=0

Remove a media clip

Remove clip 2 (MediaClip.M2).

http://<servername>/axis-cgi/mediaclip.cgi?action=remove&clip=2

List all media clips

List the current media clips on the Axis product.

Request:

http://<servername>/axis-cgi/param.cgi?action=list&group=MediaClip

The request will result in a list of all current media clips on the Axis product.

Response:

root.MediaClip.M0.Name=My new clip
root.MediaClip.M0.Location=/etc/audioclips/MediaClip.M0.au
root.MediaClip.M0.Type=audio
root.MediaClip.M1.Name=My new clip1
root.MediaClip.M1.Location=/etc/audioclips/MediaClip.M1.au
root.MediaClip.M1.Type=audio
root.MediaClip.M2.Name=My new clip2
root.MediaClip.M2.Location=/etc/audioclips/MediaClip.M2.au
root.MediaClip.M2.Type=audio

Stop a media clip

Stop any currently playing audio clips.

Request

http://<servername>/axis-cgi/mediaclip.cgi?action=stop

Parameters

Max number of media clips

MediaClip
Parameter	Default value	Valid values	Access control	Description
`MaxGroups`	`10`⁽¹⁾	1...	admin: read operator: read viewer: read	Maximum number of media clips. Read-only.
`MaxUploadSize`		1...	admin: read operator: read viewer: read	Maximum supported upload size for a media clip, measured in megabytes. If this parameter is missing, the maximum upload size is 1.5 MB.

Product/release-dependent. Check the product’s release notes.

Media clip parameters

These parameters define the media clip. There is one group for each media clip. See Manage media clips for how to create a new media clip.

Template: mediaclip
Access control – Create: admin, operator
Access control – Delete: admin, operator

MediaClip.M#
Parameter	Default value	Valid values	Access control	Description
`Name`	`Clip MediaClip.M#`	A string.	admin: read, write operator: read, write viewer: read	Descriptive name for the media clip.
`Location`	`/etc/audioclips/MediaClip.M#.au`	A local file path.	admin: read, write operator: read, write viewer: read Please note that this parameter can’t be edited with `param.cgi`.	Location of the clip. The local file path in the Axis product file system.
`Type`	`audio`	`audio`	admin: read, write operator: read, write viewer: read Please note that this parameter can’t be edited with `param.cgi`.	Media type.

Note

The # in Clip MediaClip.M# identifies the media clip and is replaced by an integer starting from 0, e.g. Clip MediaClip.M0.

Event action parameters

Media clips can be played as event actions.

Template: audioclipaction
Access control – Create: admin, operator
Access control – Delete: admin, operator
Group range: 0-19

Event.E#.Actions.A#
Parameter	Default value	Valid values	Access control	Description
`Type`	`N`	`N`	admin: write, read operator: write, read viewer: read	Type of action. N=Notification
`Protocol`	`AUDIOCLIP`	`AUDIOCLIP`	admin: write, read operator: write, read viewer: read	Protocol. Describes the type of template used for this action.
`Order`⁽¹⁾	`0`	`0...2`	admin: write, read operator: write, read viewer: read	Execution order. If an event has multiple actions, actions with the same Order will be executed in parallel (simultaneously). Actions with different Order parameters will be executed sequentially in rising order.
`Clip`	`0`	`0...<n>`	admin: write, read operator: write, read viewer: read	The media clip to play. `<n>` = The value of the `MaxGroups` parameter.

Non-functional at this time.

Note

The # in Event.E#.Action.A# are replaced by group numbers starting from zero, e.g. Event.E0.Action.A1.

AudioClip properties parameters

The parameters in the Properties.AudioClip group identify the audio clip capabilities supported by the Axis product. If the parameter does not exist in the product, then default support applies as shown in the table below.

Properties.AudioClip

Parameter	Valid values	Default support (if parameter does not exist in the product)	Access Control	Description
PlayOptions	A comma-seperated list containing any combination of `"repeat"`, `"volume"`, `"location"`, `"audiodeviceid"` or `"audiooutputid"`.	`""` (PlayOptions not supported)	Read: viewer, operator, admin	Specifies which optional arguments that are supported for play clips
StopClip	`"yes"`, `"no"`	`no` (StopClip not supported)	Read: viewer, operator, admin	Specifies if stopclip.cgi is supported
Format	A comma-seperated list containing any of the audio formats `"au"`, `"wav"`, `"opus"`, `"vorbis"` and `"mp3"`.	`"au,wav,mp3"`	Read: viewer, operator, admin	Specifies supported file formats.

API specifications

Manage media clips

Request mediaclip.cgi

The mediaclip.cgi is used to play, upload, remove, update and download media clips. Depending on the selected action, different additional arguments are supported.

Access control: admin, operator
Method: POST for action=upload, GET for all other actions

Syntax:

http://<servername>/axis-cgi/mediaclip.cgi?<argument>=<value>
[&<argument>=<value>...]

With the following arguments and values:

Argument	Values	Description
`action=<action>`	`play` `stop` `upload` `remove` `update` `download`	`play` = Play a clip `stop` = Stops the current clip `upload` = Add a new clip by uploading an audio file `remove` = Remove a clip `update` = Change the name of a clip `download` = Send a clip to the client
`clip=<int>`	`0...<n>`	The media clip the action applies to. Supported by `action=play`, `update`, `remove` and `download`. `<n>` = The value of the `MaxGroups` parameter.
`audiooutput=<int>` Optional	`1... (#index + 1 where Properties.Audio.Source.A[index].Output = "yes"#)`	Note This parameter has been deprecated as of firmware 11.7 and will no longer receive any updates. Please use `audiodeviceid` and `audiooutputid` instead. Parameter that determines what audio output that should play medicalips (`action=play`).
`media=<string>`	`audio`	Type of media when applicable. Required for `action=upload`.
`name=<string>`	Name of clip	Name of the media clip. Supported by `update` and `upload`.
`repeat=<int>`	`-1,0...`	Number of times to repeat the clip, where `-1` means repeat forever. `0` (default) means play once (no repeat). Supported by `action=play`. Supported only if PlayOptions include `repeat`
`volume=<int>`	`0...1000`	The clip volume in percentage and linear volume scale. `0` means mute. Default is `100`. Supported by `action=play`. Only supported if PlayOptions include `volume`.
`location=<uri>`	`<uri>`	Location of the clip. When using the location parameter for the play action, the clip parameter is not necessary. Accepts `*` as wildcard to play a random matching clip. Supported by `action=play`. Supported only if PlayOptions include `location`.
`audiodeviceid=<int>` Optional	`0, ...`	Parameter that determines what audio device that should play a media clip. Used as an alternative to `audiooutput` and they can not be used together. Needs to be paired with `audiooutputid` (`audiodeviceid=0&audiooutputid=0`).
`audiooutputid=<int>` Optional	`0, ...`	Parameter that determines which output on an audio device that should play a media clip. Required when `audiodeviceid` is specified.

For action=upload the POST method must be used; the file content is provided in the HTTP body. Audio files should be uploaded using Multipart/Form-Data as defined in RFC 1867.

Body:

POST /axis-cgi/mediaclip.cgi?action=upload HTTP/1.0
Content-Type: multipart/form-data; boundary=<boundary>
Content-Length: <content length>
 
--<boundary>
Content-Disposition: form-data; name="<name>";
filename="<file name>"
Content-Type: audio/basic
 
<file content>
 
--<boundary>

Response

Success for all actions except download

If the request was successful, the Axis product returns:

Return

HTTP code: 200 OK
Content-type: text/plain

Body:

OK
playing=<clip> | removed=<clip> | uploaded=<clip> | updated=<clip> | stopping

Success for action=download

For a successful download, the Axis product returns the requested media file. An audio file is returned.

Return

HTTP code: 200 OK
Content-type: audio/basic

Body:

<audio data in .au file format>

Play media clips

Request playclip.cgi

Viewers can play media clips using the playclip.cgi.

Access control: admin, operator, viewer
Method: GET

Syntax:

http://<servername>/axis-cgi/playclip.cgi?<argument>=<value>

With the following arguments and values:

Argument	Valid values	Description
`clip=<int>`	`0...<n>`	Specifies the media clip to be played. `<n>` = The value of the `MaxGroups` parameter.
`audiooutput=<int>` Optional	`1... (#index + 1 where Properties.Audio.Source.A[index].Output = "yes"#)`	Note This parameter has been deprecated as of firmware 11.7 and will no longer receive any updates. Please use `audiodeviceid` and `audiooutputid` instead. Parameter that determines what audio output that should play medicalips (`action=play`).
`repeat=<int>`	`-1,0...`	Number of times to repeat the clip, where `-1` means repeat forever. `0` (default) means play once (no repeat). Supported only if PlayOptions include `repeat`
`volume=<int>`	`0...1000`	The clip volume in percentage and linear volume scale. `0` means mute. Default is `100`. Supported only if PlayOptions include `volume`.
`location=<string>`	`<location>`	Location of the clip. When using the location parameter for the play action, the clip parameter is not necessary. Accepts `*` as wildcard to play a random matching clip. Supported only if PlayOptions include `location`.
`audiodeviceid=<int>` Optional	`0, ...`	Parameter that determines what audio device that should play a media clip. Used as an alternative to `audiooutput` and they can not be used together. Needs to be paired with `audiooutputid` (`audiodeviceid=0&audiooutputid=0`).
`audiooutputid=<int>` Optional	`0, ...`	Parameter that determines which output on an audio device that should play a media clip. Required when `audiodeviceid` is specified.

Stop media clips

Using stopclip.cgi makes it possible to stop any currently playing media clip.

Access control: viewer
Method: GET

Syntax:

http://<servername>/axis-cgi/stopclip.cgi

API responses

Successful responses for all actions except download

All actions except action=download returns the Content-Type text/plain containing OK and a description.

HTTP Code: 200 OK
Content-Type: text/plain

Body

OK
playing=<clip> | removed=<clip> | uploaded=<clip> | updated=<clip> | stopping

Response for action=download

The action action=download returns the Content-Type audio/basic containing the audio in the .au file format.

HTTP Code: 200 OK
Content-Type: audio/basic

Body

audio data in .au file format

Failure - Bad request

HTTP Code: 400 Bad Request
Content-Type: text/plain

Body

400 Bad Request
<message>

Events

Playing event

This media clip event is true whenever a media clip is played. The state is activated by HTTP API using mediaclip.cgi with action play, playclip.cgi or via action rules. It will be deactivated when either the media clip is finished or by using the HTTP API method stop.cgi.

Topic: tnsaxis:MediaClip/tnsaxis:Playing
Type: Stateful
Nice name: Playing state

Field name	Type	Nice name	Description	Values
Source fields
`AudioOutput`	Integer	AudioOutput	Note This parameter has been deprecated as of firmware 11.7 and will no longer receive any updates. Audio output if state is relevant. 0 if undefined.	`0... (if 1+ index as in Properties.Audio.Source.A[AudioOuput - 1].Output = "yes" #)`
`audiodeviceid`	Integer	AudioDeviceId	Parameter that determines what audio device that should play a media clip. Used as an alternative to audiooutput and they can not be used together. Needs to be paired with `audiooutputid` `(audiodeviceid=0&audiooutputid=0)`.	`0...`
`audiooutputid`	Integer	AudioOutputId	Parameter that determines which output on an audio device that should play a media clip. Required when `audiodeviceid` is specified.	`0...`
Data fields
`Playing (STATE)`	Boolean	Playing status	True when active.	True/False

CurrentlyPlaying event

This media clip event is will be triggered whenever the Playing state is true and a new media clip is played. Using the repeat option will trigger this event multiple times.

Topic: tnsaxis:MediaClip/tnsaxis:CurrentlyPlaying
Type: Stateless
Nice name: Currently playing media clip

Field name	Type	Nice name	Description	Values
Source fields
`AudioOutput`	Integer	AudioOutput	Note This parameter has been deprecated as of firmware 11.7 and will no longer receive any updates. Audio output if state is relevant. 0 if undefined.	`0... (if 1+ index as in Properties.Audio.Source.A[AudioOuput - 1].Output = "yes" #)`
`audiodeviceid`	Integer	AudioDeviceId	Parameter that determines what audio device that should play a media clip. Used as an alternative to audiooutput and they can not be used together. Needs to be paired with `audiooutputid` `(audiodeviceid=0&audiooutputid=0)`.	`0...`
`audiooutputid`	Integer	AudioOutputId	Parameter that determines which output on an audio device that should play a media clip. Required when `audiodeviceid` is specified.	`0...`
Data fields
`FileName`	String	File Name	File name of played clip.	String containing the name.