Axis VAPIX User Manual

VAPIX®VERSION3

VideoStreamingAPI

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

COPYRIGHTNOTICE

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedor
distributedinanywaywithoutthepriorwrittenconsentofAxisCommunicationsAB.

VAPIX®LICENSEAGREEMENT

ThisVAPIX®LicenseAgreement(“License”)isalegalagreementbetweenyou(eitherindividualoranentity)andAxisCommunications
AB(“Axis”).ByusingtheINTERFACEandINTERFACEDESCRIPTION(eachdenedbelow),whetherinwholeorinpart,youagreetobe
boundbythetermsofthisLicense.

1.GRANTOFLICENSE

AxisherebygrantstoyoutherighttousetheAXISVAPIXapplicationprogramminginterface(“INTERFACE”)andthewritten
specicationoftheINTERFACE(the“INTERFACEDESCRIPTION”)forthesoleandlimitedpurposeofcreating,manufacturingand
developingasolutionthatintegratesanyunitorportionincludedintheproductrangeofAxisnetworkproducts,asdenedbyAxisat
itsdiscretion(an“AxisProduct”)andtomarket,sellanddistributeanysuchsolution.

2.COPYRIGHT

TheINTERFACEandtheINTERFACEDESCRIPTIONareownedbyAxisandareprotectedbycopyrightlawsandinternationaltreaty
provisions.AnyuseoftheINTERFACEand/ortheINTERFACEDESCRIPTIONoutsidethelimitedpurposesetforthinSection1
aboveisstrictlyprohibited.

3.RESTRICTIONSONUSE

YouhavenorightswithrespecttotheINTERFACE,INTERFACEDESCRIPTIONoranyportionsthereofandshallnotusetheINTERFACE,
INTERFACEDESCRIPTIONoranyportionthereofexceptasexpresslysetforthherein.Youmaynotreverseengineer,decompile,or
disassembletheINTERFACEexcepttotheextentrequiredtoobtaininteroperabilitywithotherindependentlycreatedcomputer
programsaspermittedbymandatorylaw.

4.THIRDPARTYRIGHTS

YouagreethatyouarefullyresponsibleforyourownconductwhileusingtheINTERFACEandintegratinganyAxisProductsinto
yoursolutionandtheconsequencesthereof.AxisProductsmaybecombinedwithavirtuallyinnitenumberofpotentialsolutions.
Consequently,yourecognizethat(i)otherthirdpartiesmayclaimtoownpatentsorcopyrightsthatcouldcovercertainsolutions
whichintegrateAxisproducts,orwhichresultfromthecombinationofAxisproductsandadditionaltechnologyorsolutionsand(ii)
youareresponsibleforensuringthatanysolutionwhichintegrateswithanAxisProduct,oracombinationofasolutionandanAxis
product,doesnotinfringeuponormisappropriateanyintellectualpropertyorpersonalrightofanythirdparty.

5.TERMINATION

ThisLicenseiseffectiveuntilterminated.YourrightsunderthisLicensewillterminateautomaticallywithoutnoticefromAxisifyou
failtocomplywithanyterm(s)ofthisLicense.UpontheterminationofthisLicense,youshallceasealluseanddispositionofthe
INTERFACEand/orTHEINTERFACEDESCRIPTIONwhetherforthepurposesetforthinSection1aboveornot.

6.REPRESENTATIONSANDWARRANTIES;DISCLAIMER

6.1.Yourepresentandwarrantthat(i)anysolutioncreated,manufacturedand/ordevelopedbyyouwhichintegratesanAxis
Productshallnotinfringeorotherwiseviolateanythirdpartyrights,includingbutnotlimitedtothirdpartyintellectual
propertyrights;and(ii)youruseoftheINTERFACEandINTERFACEDESCRIPTIONwillcomplywithallapplicableforeignand
domesticlaws,rulesandregulations.

6.2.YOURUSEOFTHEINTERFACEISATYOURSOLERISK.THEINTERFACEANDTHEINTERFACEDESCRIPTIONAREDELIVEREDFREE
OFCHARGEAND"ASIS"WITHOUTWARRANTYOFANYKIND.THEENTIRERISKASTOTHEUSE,RESULTSANDPERFORMANCE
OFTHEINTERFACEANDTHEINTERFACEDESCRIPTIONISASSUMEDBYTHEUSER/YOU.AXISDISCLAIMSALLWARRANTIES,
WHETHEREXPRESSORIMPLIED,INCLUDINGBUTNOTLIMITEDTO,THEIMPLIEDWARRANTIESOFMERCHANTABILITY,
FITNESSFORAPARTICULARPURPOSE,TITLE,NON-INFRINGEMENTANDPRODUCTLIABILITY,ORANYWARRANTYARISING
OUTOFANYPROPOSAL,SPECIFICATIONORSAMPLEWITHRESPECTTOTHEINTERFACEANDTHEINTERFACEDESCRIPTION.
Withoutlimitingthegeneralityoftheforegoing,youacknowledgeandagreethatAxisdoesnotmakeanyrepresentation
orwarrantythattheintegrationofAxisProductsintoyoursolutiondoesnotinfringeanythirdpartyrights.Youaresolely
responsibleforanyintellectualpropertyinfringementclaimsthatarebasedonorrelatetosolutionscreated,manufactured
anddistributedbyyouwhichintegrateAxisProducts.Axisisunawareofthedetailsregardingyourparticularsolution,
hasnotconductedanyinvestigationrelatingtopotentialthirdpartyrightsissuesrelatingtoyoursolutionanddoesnot
acceptanyresponsibilityorliabilitywithrespectthereto.

6.3.THISLICENSEDOESNOTCONVEYANYLICENSETOTHIRDPARTYINTELLECTUALPROPERTY.YOUARESOLELYRESPONSIBLE
FOR(I)EXAMININGWHETHERTHEINTERFACEANDTHEINTERFACEDESCRIPTIONAREENCUMBEREDBYORINFRINGESUPON
ARIGHTHELDBYATHIRDPARTYAND(II)ANYINTELLECTUALPROPERTYINFRINGEMENTCLAIMSTHATARISEOUTOFOR
RELATETOSOLUTIONSCREATED,MANUFACTUREDANDDISTRIBUTEDBYYOUWHICHINTEGRATEAXISPRODUCTS.

2

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

7.LIMITATIONOFLIABILITY

7.1.AXISSHALLNOTBELIABLEFORLOSSOFDATA,LOSSOFPRODUCTION,LOSSOFPROFIT,LOSSOFUSE,LOSSOFCONTRACTSOR
FORANYOTHERCONSEQUENTIAL,ECONOMICORINDIRECTLOSSWHATSOEVERINRESPECTOFUSEORDISPOSITIONOFTHE
INTERFACEANDTHEINTERFACEDESCRIPTION.

7.2.AXISTOTALLIABILITYFORALLCLAIMSINACCORDANCEWITHTHEUSEOFTHEINTERFACEANDTHEINTERFACEDESCRIPTION SHALLNOTEXCEEDTHEPRICEPAIDFORTHEINTERFACEANDTHEINTERFACEDESCRIPTION.

7.3.YOUUNDERTAKENOTTOPURSUEANYCLAIMSWHATSOEVERAGAINSTAXISORITSAFFILIATESRELATINGTOOREMANATING FROMTHEINTERFACEANDTHEINTERFACEDESCRIPTIONORYOURINTEGRATIONOFANAXISPRODUCTINTOYOURSOLUTION.

8.INDEMNIFICATION

YouwillindemnifyandholdAxis,itssubsidiaries,afliates,ofcers,employees,andagentsharmlessfromanyandallclaims,
damages,losses,liabilities,actions,judgments,costs,andexpensesbroughtbyathirdparty,includingclaimsforinfringementof
intellectualpropertyrights,arisingoutoforinconnectionwith(i)youruseoftheINTERFACEorINTERFACEDESCRIPTIONother
thaninaccordancewiththetermsofthisagreement,and/or(ii)anysolutioncreated,manufacturedand/ordevelopedbyyouwhich
integratesanAxisProduct.

9.GOVERNINGLAW

ThisagreementshallbedeemedperformedinandshallbeconstruedbythelawsofSweden.Alldisputesinconnectionwith
thisagreementshallbenallysettledbyarbitrationinaccordancewiththeRulesoftheArbitrationInstituteoftheStockholm
ChamberofCommerce.TheplaceofarbitrationshallbeMalmö,Sweden.Thelanguageoftheproceedings,documentationand
theawardshallbeEnglish.

3

VideoStreamingAPI

TableofContents

1Overview...............................................6

1.1Description...............................................6

1.1.1References...........................................6

1.2UnknownArguments.......................................6

2VideoStreamingOverHTTP...............................7

2.1Prerequisites..............................................7

2.1.1Identication.........................................7

2.2CommonExamples.........................................7

2.3ImageResolution..........................................7

2.3.1ImageResolutionRequest...............................7

2.3.2ImageResolutionResponse..............................8

2.4VideoStatus..............................................9

2.4.1VideoStatusRequest...................................9

2.4.2VideoStatusResponse..................................9

2.5Bitmap...................................................10

2.5.1BitmapImageRequest..................................10

2.5.2BitmapImageResponse.................................10

2.6JPEG/MotionJPEG.........................................11

2.6.1JPEGImage(Snapshot)CGIRequest.......................11

2.6.2JPEGImageResponse...................................11

2.6.3MotionJPEGVideoCGIRequest..........................12

2.6.4MotionJPEGVideoResponse.............................13

2.7ImageRequestArguments...................................13

3RTSPAPI...............................................15

3.1Prerequisites..............................................15

3.1.1Identication.........................................15

3.2RTSPCommands...........................................15

3.2.1RequestSyntax........................................15

3.2.2ResponseSyntax.......................................16

3.2.3RTSPDESCRIBE........................................16

3.2.4SDPMediaAttributeTransform...........................17

3.2.5RTSPOPTIONS.........................................18

3.2.6RTSPSETUP...........................................18

3.2.7RTSPPLAY............................................19

3.2.8RTSPPAUSE..........................................20

3.2.9RTSPTEARDOWN......................................21

3.2.10RTSPSET_PARAMETER.................................21

3.3RTSPOverHTTP............................................22

3.3.1NetworkParameters....................................23

3.4ParameterSpecicationRTSPURL.............................23

3.5ErrorMessagesRTSP........................................26

3.6RTCP....................................................26

4AlwaysMulticast........................................27

4.1Prerequisites..............................................27

4.1.1Identication.........................................27

4.2SDP.....................................................27

4.2.1RequestSDPURL......................................27

4.2.2ResponseSDPURL.....................................27

5StreamProles..........................................28

5.1Prerequisites..............................................28

5.1.1Identication.........................................28

5.2CommonExamples.........................................28

5.3StreamProleParameters...................................29

5.4MotionJPEGVideoRequest..................................30

4

VideoStreamingAPI

TableofContents

5.5RTSPRequest.............................................31

©2008-2013AxisCommunicationsAB.AXISCOMMUNICATIONS,AXIS,ETRAX,ARTPECandVAPIXareregisteredtrademarksor
trademarkapplicationsofAxisABinvariousjurisdictions.Allothercompanynamesandproductsaretrademarksorregistered
trademarksoftheirrespectivecompanies.Wereservetherighttointroducemodicationswithoutnotice.

5

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

1Overview

1.1Description

Thisdocumentexplainsthebasicargumentsandparameterstosend,receiveandcongureavideostreamusingHTTPorRTSPrequests.

1.1.1References

AllVAPIX®referencesareavailableat:

http://www.axis.com/vapix

1.2UnknownArguments

Ifanunknownargumentisrequested,forexampleifanargumentismisspelleditwillbeignoredbythebuilt-inserverintheAxis
product.Thatmeansthatnoresponsefeedbackwillbegiven.

6

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

2VideoStreamingOverHTTP

TheHTTP-basedvideointerfaceprovidesthefunctionalityforrequestingsingleandmultipartimagesandforgettingandsetting
internalparametervalues.TheimageandCGIrequestsarehandledbythebuilt-inwebserver.

2.1Prerequisites

2.1.1Identication

Property:Properties.API.HTTP.Version=3
Firmware:5.00andlater.

2.2CommonExamples

Example1:

ChecksupportedVAPIX®version.

http://myserver/axis-cgi/param.cgi?action=list&group=Properties.API.HTTP.Version

Example2:

Checksupportedresolutions.

http://myserver/axis-cgi/param.cgi?action=list&group=Properties.Image.Resolution

Example3:

Checksupportedimageformats.

http://myserver/axis-cgi/param.cgi?action=list&group=Properties.Image.Format

Example4:

Checkthedefaultresolutionofvideosource1.

http://myserver/axis-cgi/imagesize.cgi?camera=1

Example5:

RequestaMotionJPEGvideostream.

http://myserver/axis-cgi/mjpg/video.cgi

2.3ImageResolution

Byusingtheimagesize.cgiyoucanndouttherealimageresolutionsdependingonthevideoformat(PAL/NTSC).Youcanalso
verifythatdesiredresolutionaswellasresolutionafterrotation.

2.3.1ImageResolutionRequest

Theimagesize.cgiisusedtoretrievetheimageresolution.

Accesscontrol:viewer
Method:GET/POST

7

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

Syntax:

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

Withthefollowingargumentsandvalues:

ArgumentDescription

Anyimageargument.

Example6:

Checkthedefaultresolutionofvideosource1.

Request:

http://myserver/axis-cgi/imagesize.cgi?camera=1

Response:

imagewidth=720
imageheight=576

See2.7ImageRequestArgumentsforimageCGIarguments.

Example7:

Requestaspecicresolutionwithsuppliedparametersforvideosource1.

Request:

http://myserver/axis-cgi/imagesize.cgi?resolution=QCIF&rotation=180
&squarepixel=1&camera=1

Response:

imagewidth=192
imageheight=144

2.3.2ImageResolutionResponse

Whenanimageresolutionisrequested,theAxisproducteitherreturnsaresolutionvalueoranerror.

2.3.2.1SuccessfulRequest

Theimageheightandwidthinpixelsarereturnedafterasuccessfulrequest.

Response:

HTTPCode:200OK
Content-Type:text/plain

Body:

imagewidth=<value>
imageheight=<value>

2.3.2.2Failure

IfanAxisproductdoesnotsupporttherequestedresolutionabodytextisreturnedwithinfo.Forexample<!--Camera1
notavailable.-->.

8

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

Response:

HTTPCode:200OK
Content-Type:text/plain

Body(valueforargument"camera"isspecied):

<!--[errormessage]-->

Body(valueforargument"camera"isnotspecied):

[errormessage]

2.4VideoStatus

Thissectiononlyappliestovideoencoders.Thevideostatus.cgiisusedtocheckthestatusofoneormorevideosources.

2.4.1VideoStatusRequest

Requestthestatusinformationforthevideosources.ThenumberofvideosourcesinanAxisproductisdenedbytheparameter
ImageSource.NbrOfSources.

Accesscontrol:viewer
Method:GET

Syntax:

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

Withthefollowingargumentandvalues:

ArgumentValidvaluesDescription

status=<int>[[,<int>],...]1...

1.Product-dependent.

1

2.4.2VideoStatusResponse

Getthestatusinformationforthevideosources.

Response:

HTTPCode:200OK
Content-Type:text/plain

Body:

Video1=<information>
...

Checkstatusofthelistedvideosources.

<information>couldbeeithervideoornovideo.

Example8:

Requestvideostatusfromvideosource1,2,3and4.

http://myserver/axis-cgi/videostatus.cgi?status=1,2,3,4

Response:

9

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

Returneddataafterasuccessfulrequest.

HTTPCode:200OK
Content-Type:text/plain

Body:

Video1=video
Video2=novideo
Video3=novideo
Video4=video

Theresponsenovideomeansthatthereisnoanalogvideosignalattachedtothephysicalvideoinputport.

2.5Bitmap

Supportforbitmapimagesisproduct-dependent.Usethefollowingcommandtochecksupportedimageformats.

http://myserver/axis-cgi/param.cgi?action=list&group=Properties.Image.Format

Responseexample:

properties.image.format=jpeg,mjpeg,h264,bitmap

TheresponseshowsthattheAxisproductintheexamplesupportsbitmapimages.

2.5.1BitmapImageRequest

Thesyntaxbitmap/image.bmpisusedtorequestabitmapimage.

Accesscontrol:viewer
Method:GET

Syntax:

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

Withthefollowingargumentsandvalues:

ArgumentDescription

Bitmapimagearguments.

Example9:

Requestabitmapimagefromthedefaultvideosourceusingdefaultsettings.

http://myserver/axis-cgi/bitmap/image.bmp

See2.7ImageRequestArgumentsforarguments.

Example10:

Requestabitmapimagefromvideosource1withresolution320x240.

http://myserver/axis-cgi/bitmap/image.bmp?resolution=320x240&camera=1

2.5.2BitmapImageResponse

Whenabitmapimageisrequested,theAxisproducteitherreturnsthespeciedbitmapimageleoranerror.

10

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

2.5.2.1SuccessfulRequest

SuccessfulresponsetoaHTTPrequest.

Response:

HTTPCode:200OK
Content-Type:image/bitmap
Content-Length:<imagesizeinbytes>

Body:

<bitmapimagedata>

2.6JPEG/MotionJPEG

TherequestsspeciedinthissectionrefertoAxisproductsthataresettouseJPEGandMotionJPEGencoding.

2.6.1JPEGImage(Snapshot)CGIRequest

Thejpg/image.cgiisusedtorequestaJPEGimage(snapshot).AJPEGimage(snapshot)shouldonlybeusedwhenrequiring
lessthan1fps.

Accesscontrol:viewer
Method:GET

Syntax:

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

Withthefollowingargumentsandvalues:

ArgumentDescription

JPEGimagearguments.See2.7ImageRequestArgumentsforarguments.

Example11:

RequestaJPEGimagefromvideosource1withresolution320x240andcompression25.

http://myserver/axis-cgi/jpg/image.cgi?resolution=320x240
&compression=25&camera=1

Example12:

RequestaJPEGimagefromvideosource2withthetextMyCameradisplayed.

http://myserver/axis-cgi/jpg/image.cgi?
&text=1&textstring=My%20Camera&camera=2

2.6.2JPEGImageResponse

WhenaJPEGimageisrequested,theAxisproducteitherreturnsthespeciedJPEGimageoranerror.

2.6.2.1SuccessfulRequest

SuccessfulresponsetoaHTTPrequest.

Response:

11

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

HTTPCode:200OK
Content-Type:image/jpeg
Content-Length:<imagesizeinbytes>

Body:

<JPEGimagedata>

2.6.3MotionJPEGVideoCGIRequest

Themjpg/video.cgiisusedtorequestaMotionJPEGvideostreamwithspeciedarguments.Theargumentscanbespecied
explicitly,orapredenedstreamprolecanbeused.Imagesettingssavedinastreamprolecanbeoverriddenbyspecifying
newsettingsafterthestreamproleargument.

Accesscontrol:viewer
Method:GET

Syntax:

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

Inadditiontotheargumentsdescribedin2.7ImageRequestArguments,onpage13mjpg/video.cgiacceptsthefollwing
arguments.

ArgumentValidvaluesDescription

streamprofile=<string><streamprofilename>

duration=<int>

nbrofframes=<int>

fps=<int>

Generalimagearguments,see2.7ImageRequestArguments.

Example13:

RequestaMotionJPEGvideostreamfromvideosource1withresolution320x240andcompression25.

http://myserver/axis-cgi/mjpg/video.cgi?resolution=320x240
&compression=25&camera=1

Anunsignedinteger

Anunsignedinteger

AnunsignedintegerUsingfpsitispossibletospecifythe

Useapredenedstreamprole.
Supportedstreamprolenamesarestored
intheStreamProfile.S#.Name
parameters.

Speciesforhowmanysecondsthevideo
willbegeneratedandpushedtothe
client.
0=unlimited.

SpecieshowmanyframestheAxis
productwillgenerateandpush.
0=unlimited.

frameratefromtheAxisproduct.
0=unlimited.

Example14:

RequestaMotionJPEGvideostreamfromthedefaultvideosourcewithframerate5.

http://myserver/axis-cgi/mjpg/video.cgi?fps=5

Example15:

RequestaMotionJPEGvideostreamusingthemyprofilestreamprolebutwithalowerresolution.

12

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

http://myserver/axis-cgi/mjpg/video.cgi?
streamprofile=myprofile&resolution=CIF

2.6.4MotionJPEGVideoResponse

WhenaMotionJPEGvideoisrequested,theAxisproducteitherreturnsthespeciedMotionJPEGvideooranerror.

2.6.4.1SuccessfulRequest

Iftherequestwassuccessful,theAxisproductreturnsacontinuousowofJPEGimages.Thecontenttypeis
multipart/x-mixed-replaceandeachimageendswithaboundarystring<boundary>.

Response:

HTTPCode:200OK
Content-Type:multipart/x-mixed-replace;boundary=<boundary>

Body:

--<boundary>
<image>

--<boundary>
<image>

Wherethereturned<image>eldis:

Content-Type:image/jpeg
Content-Length:<imagesizeinbytes>

<JPEGimagedata>

2.7ImageRequestArguments

ThefollowingargumentsandvaluescanbeusedinJPEG,MotionJPEGorbitmapCGIrequests.Unlessoverriddenbyaargumentitis
thedefaultvaluesasconguredviatheGUI(orparam.cgi)thatdecidesthecharacteristicsoftheimageorvideo.

ArgumentValidvaluesDescription

resolution=<string>

camera=<string>

compression=<int>0...100

1

Astring

1...
quad

1

Resolutionofthereturnedimage.For
supportedresolutions,checkinparameter

Properties.Image.Resoluti­on.

Selectsthevideosource.Ifomittedthe
defaultvaluecamera=1isused.This
argumentisonlyvalidforAxisproducts
withmorethanonevideosource.That
iscameraswithmultipleviewareas
andvideoencoderswithmultiplevideo
channels.

Adjuststhecompressionlevelofthe
image.Highervaluescorrespondto
highercompression,thatislowerquality
andsmallerimagesize.Note:Thisvalue
isinternallymappedandistherefore
product-dependent.

13

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

rotation=<int>0

1

90

1

180

1

270

squarepixel=<int>0

1

1.Product/release-dependent.

Note

ForargumentsconcerningoverlaysrefertotheOverlaydocumentavailableat:

http://www.axis.com/techsup/cam_servers/dev/cam_http_api_index.php

Rotatetheimageclockwise.Thenumber
ofrotationalternativesinanAxis
productisdenedbytheparameter
Properties.Image.Rotation.

Enable/disablesquarepixel(aspectratio)
correction.Iftheparameterissetto1
theAxisproductwilladjuststheaspect
ratiotomakeitappearasintended.

14

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

3RTSPAPI

RTSP(RealTimeStreamingProtocol)isacontrolprotocolformediastreamsdeliveredbyamediaserver.RTSPcanbeconsidereda
“remotecontrol”providingcommandssuchasplayandpause.Inaddition,RTSPAPIprovidesparameterscontrollingmediastream
propertiessuchasresolution,compression,videobitrateandaudioaswellasparameterscontrollingtheimagesettings.

Pleaserefertothereleasenotesfortheactualproductforcomplianceinformation.

TheRTSPserverintheAxisproductsisbasedonRFC2326RealTimeStreamingProtocol(RTSP),RFC4566SDP:SessionDescription
ProtocolandRFC3550RTP:ATransportProtocolforReal-TimeApplications.

WhenstreamingbothvideoandaudiotheaudioandvideocanbesynchronizedbyusingRTPtimestampsasdescribedinRFC3550.

3.1Prerequisites

3.1.1Identication

Property:Properties.API.RTSP.Version=2.01andlater
Property:Properties.API.RTSP.RTSPAuth=yes

3.2RTSPCommands

TheRTSPAPIprovidesseveralcommandsformediastreamcontrol.

3.2.1RequestSyntax

Syntax:

COMMANDrtsp://<servername>/axis-media/media.amp
[?<parameter>=<value>[&<parameter>=<value>...]]RTSP/1.0<CRLF>
Headerfield1:val1<CRLF>
Headerfield2:val2<CRLF>
...
<CRLF>

[Body]

COMMANDisanyofDESCRIBE,SETUP,OPTIONS,PLAY,PAUSE,TEARDOWN,SET_PARAMETERorGET_PARAMETER.Lines

areseparatedwithCarriageReturnandLineFeed(CRLF).

SupportedRTSPURLparametersandtheirvaluesarelistedinsection3.4ParameterSpecicationRTSPURL.

Note

RTSPrequestsalwayscontaintheabsoluteURL.

Thefollowingheadereldsareacceptedbyallcommands.Somecommandsacceptorrequireadditionalheaderelds:

HeaderFieldDescription

Authorization

CSeq

Session

Content-Length

Authorizationinformationfromtheclient.

Requestsequencenumber.

Sessionidentier(returnedbytheAxisproductinSETUP
response).

Lengthofcontent.

15

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

Content-Type

User-Agent

Require

Themediatypeofthecontent.

Informationabouttheclientthatinitiatestherequest.

Querywhetheranoptionissupported.Unsupportedfeatures
arelistedintheUnsupportedheadereld.Seeexample2in
section3.2.10RTSPSET_PARAMETER.

3.2.2ResponseSyntax

Syntax:

RTSP/1.0<StatusCode><ReasonPhrase><CRLF>
Headerfield1:val3<CRLF>
Headerfield2:val4<CRLF>
...

[Body]

Therstresponselinecontainsastatuscodeandareasonphraseindicatingthesuccessorfailureoftherequest.Thestatuscodes
aredescribedinRFC2326.

ThefollowingheadereldscanbeincludedinallRTSPresponsemessages:

HeaderFieldDescription

CSeq

Session

WWW-Authenticate

Date

Unsupported

Responsesequencenumber(matchesthesequencenumberof
therequest).

Sessionidentier.

Authenticationfromclientrequested.

Dateandtimeoftheresponse.

FeaturesnotsupportedbytheAxisproduct.

3.2.3RTSPDESCRIBE

TheDESCRIBEcommandisusedtorequestanSDPdescriptionofthemediastream(s).TheSessionDescriptionProtocol(SDP)is
describedinRFC2327.

TheDESCRIBErequestacceptstheadditionalheadereld:

HeaderFieldDescription

Accept

TheresponsetotheDESCRIBEcommandcontainstheadditionalheaderelds:

HeaderFieldDescription

Content-Type

Content-Length

Content-Base

Example1:

Listofcontenttypesthatclientsupports(application/sdp
istheonlysupportedtype).

Typeofcontent(application/sdp).

LengthofSDPdescription.

IfrelativeURLsareusedintheSDPdescription,thisisthebase
URL.

16

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

Request:

DESCRIBErtsp://myserver/axis-media/media.amp
?videocodec=h264&resolution=640x480RTSP/1.0
CSeq:0
User-Agent:AxisAMC
Accept:application/sdp

Response:

RTSP/1.0200OK
CSeq:0
Content-Type:application/sdp
Content-Base:rtsp://myserver/axis-media/media.amp/
Date:Wed,16Jul200812:48:47GMT
Content-Length:847

v=0
o=-12162125275548721216212527554872INIP4myserver
s=MediaPresentation
e=NONE
c=INIP40.0.0.0
b=AS:50064
t=00
a=control:rtsp://myserver/axis-media/media.amp?videocodec=h264
&resolution=640x480
a=range:npt=0.000000­m=video0RTP/AVP96
b=AS:50000
a=framerate:30.0
a=transform:1,0,0;0,1,0;0,0,1
a=control:rtsp://myserver/axis-media/media.amp/trackID=1?videocodec=h264
&resolution=640x480
a=rtpmap:96H264/90000
a=fmtp:96packetization-mode=1;profile-level-id=420029;
sprop-parameter-sets=Z0IAKeKQFAe2AtwEBAaQeJEV,aM48gA==
m=audio0RTP/AVP97
b=AS:64
a=control:rtsp://myserver/axis-media/media.amp/trackID=2
?videocodec=h264&resolution=640x480
a=rtpmap:97mpeg4-generic/16000/1
a=fmtp:97profile-level-id=15;mode=AAC-hbr;config=1408;SizeLength=13;
IndexLength=3;IndexDeltaLength=3;Profile=1;bitrate=64000;

3.2.4SDPMediaAttributeTransform

Dependingonproductmodel,theSDPlemaycontainavideomediaattributetransform.Ifthestreamedvideoisrotatedor
mirroredfromtheimagesource,thisvideomediaattributeshowshowthevideostreamisorientatedinrelationtotheoriginalimage
conguration.Theorientationisdescribedbyatransformationmatrixconsistingofhomogeneouscoordinatesfortwo-dimensional
operations(a3x3matrix).

Syntax:

a=transform:<MATRIX>

Thematrixisformattedusingcommastoseparatecolumnsandsemicolonstoseparaterows.

Example2:

Avideostreamwhichisrotated90degreesisdescribedby:

17

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

a=transform:0,-1,0;1,0,0;0,0,1

3.2.5RTSPOPTIONS

TheOPTIONSrequestreturnsalistofsupportedRTSPcommands.ThecommandcanbeusedtokeepRTSPsessionsaliveby
repeatingtheOPTIONSrequestatregularintervals.Thesessiontimeouttimeisspeciedbythetimeoutparameterreturnedfrom
theSETUPcommand(see3.2.6RTSPSETUP).

TheresponsetotheOPTIONScommandcontainstheadditionalheadereld:

Headereld

Public

Example3:

Listsupportedcommands.Theasterisk(*)makestherequestapplytotheserverandnottoaparticularURL.

Request:

OPTIONS*RTSP/1.0
CSeq:1
User-Agent:AxisAMC
Session:12345678

Response:

RTSP/1.0200OK
CSeq:1
Session:12345678
Public:DESCRIBE,GET_PARAMETER,PAUSE,PLAY,SETUP,SET_PARAMETER,TEARDOWN
Date:Wed,16Jul200812:48:48GMT

Note

Asindicatedintheresponse,theGET_PARAMETERcommandissupported;therearehowevernoparameterstoretrieve.

Description

SpecifythesupportedRTSPcommands.

3.2.6RTSPSETUP

TheSETUPcommandisusedtocongurethedatadeliverymethod.

TheSETUPrequestrequiresanadditionalheadereldwhichisalsoincludedintheresponse:

Headereld

Transport

IfusingunicastincombinationwithTCP,itisrecommendedtoincreasethesizeoftheRTPpacketsto64000bytes(fromthestandard
1500bytes),providedthattheclientcanacceptlargerpackets.AlsoforunicaststreamingoverRTP/UDPitmightbebenecialto
increasethepacketsizeifnopacketsaredropped.ThepacketsizeischangedusingthefollowingheadereldintheSETUPrequest:

Headereld

Blocksize

Description

Specifyhowthedatastreamistransported.Supportedvariants
are:

RTP/AVP;unicast;client_port=port1-port2
RTP/AVP;multicast;client_port=port1-port2
RTP/AVP/TCP;unicast

Description

Requestaspecicmediapacketsize.Thepacketsizeshouldbe
apositivedecimalnumbermeasuredinoctets.

18

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

Theresponsereturnsasessionidentierthatshouldbeusedtogetherwiththestreamcontrolcommands(forexamplePLAY,
PAUSEandTEARDOWN).Ifthesessionheaderincludesthetimeoutparameter,thesessionwillcloseafterthetimeouttimeunless
explicitlykeptalive.SessioncanbekeptalivebysendingRTSPrequeststotheAxisproductcontainingthesessionidentier(for
exampleOPTIONS,see3.2.5RTSPOPTIONS)withinthetimeouttimeorbyusingRTCPmessages.Recongurationoftransport
parametersisnotsupported.

Example4:

TheresponsetotherstSETUPrequestreturnsthesessionidentier(Session)whichisusedinsubsequentrequests.Theparameter
trackIDshouldbereadfromDESCRIBEandusedinSETUP.

Request:

SETUPrtsp://myserver/axis-media/media.amp/
trackID=1?videocodec=h264&resolution=640x480RTSP/1.0
CSeq:2
User-Agent:AxisAMC
Transport:RTP/AVP;unicast;client_port=20000-20001

Response:

RTSP/1.0200OK
CSeq:2
Session:12345678;timeout=60
Transport:RTP/AVP;unicast;client_port=20000-20001;
server_port=50000-50001;ssrc=B0BA7855;mode="PLAY"
Date:Wed,16Jul200812:48:47GMT

Example5:

Request:

SETUPrtsp:///myserver//axis-media/media.amp/
trackID=2?videocodec=h264&resolution=640x480RTSP/1.0
CSeq:3
User-Agent:AxisAMC
Transport:RTP/AVP;unicast;client_port=20002-20003
Session:12345678

Response:

RTSP/1.0200OK
CSeq:3
Session:12345678;timeout=60
Transport:RTP/AVP;unicast;client_port=20002-20003;
server_port=50002-50003;ssrc=D7EB59C0;mode="PLAY"
Date:Wed,16Jul200812:48:48GMT

3.2.7RTSPPLAY

ThePLAYrequeststarts(orrestartsifpaused)thedatadeliverytotheclient.

Note

WhenplayingMotionJPEGviaRTSPthereisaresolutionlimitof2040x2040pixels.

TheresponsetothePLAYcommandcontainstheadditionalheaderelds:

19

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

Headereld

Range

RTP-Info

Example6:

Request:

PLAYrtsp://myserver/axis-media/media.amp
?videocodec=h264&resolution=640x480RTSP/1.0
CSeq:4
User-Agent:AxisAMC
Session:12345678

Response:

RTSP/1.0200OK
CSeq:4
Session:12345678
Range:npt=0.645272­RTP-Info:url=rtsp://myserver/axis-media/media.amp/
trackID=1?videocodec=h264&resolution=640x480;seq=46932;
rtptime=1027887748,url=rtsp://myserver/axis-media/media.amp/
trackID=2?videocodec=h264&resolution=640x480;seq=3322;rtptime=611053482
Date:Wed,16Jul200812:48:48GMT

Description

Theplaytimeperiod.

InformationabouttheRTPstream,includingthesequence
numberoftherstpacketofthestream.

Example7:

Playtherecording“myrecording”.

Request:

PLAYrtsp://myserver/axis-media/media.amp?recordingid=”myrecording”RTSP/1.0
CSeq:4
User-Agent:AxisAMC
Session:12345678

3.2.8RTSPPAUSE

ThePAUSErequestisusedtotemporarilystopdatadeliveryfromtheAxisproduct.UsePLAYtorestartdatadelivery.

Example8:

Request:

PAUSErtsp://myserver/axis-media/media.amp
?videocodec=h264&resolution=640x480RTSP/1.0
CSeq:5
User-Agent:AxisAMC
Session:12345678

Response:

RTSP/1.0200OK
CSeq:5
Session:12345678
Date:Wed,16Jul200812:48:49GMT

20

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

3.2.8.1RTSPPAUSEOnLiveStream

IfPAUSEisrequestedduringlivestreamingthedatatransmissionwillstopimmediately.IfPLAYlaterisrequestedthelivesteam
startsonthelatestsampledframe.Thatmeansthattheclientwilllosethevideoduringthetimethatthestreamhasbeenpaused.
TheclientisnotiedintheRangeheaderwhichintervalthatwillbestreamed.

3.2.9RTSPTEARDOWN

TheTEARDOWNrequestisusedtoclosethedatadeliveryfromtheAxisproduct.

Example9:

Request:

TEARDOWNrtsp://myserver/axis-media/media.amp
?videocodec=h264&resolution=640x480RTSP/1.0
CSeq:6
User-Agent:AxisAMC
Session:12345678

Response:

RTSP/1.0200OK
CSeq:6
Session:12345678
Date:Wed,16Jul200812:49:01GMT

3.2.10RTSPSET_PARAMETER

TheSET_PARAMETERcommandisusedtochangesessionparameters,currentlyonlyI-framerequestissupported.Thecommand
setstheRenew-Streamparametertoyes.

Note

Renew-Streammustbesentinthebody.ThecorrespondingRenew-Streamparameterinsomermware4.xxproducts
hadtobesentintheheader.Seeexample2below.

Example10:

UseofSET_PARAMETERinrmware5.xxproducts.Renew-Streamissentinthebody.

Request:

SET_PARAMETERrtsp://myserver/axis-media/media.ampRTSP/1.0
CSeq:7
Session:12345678
Content-Type:text/parameters
Content-Length:19

Renew-Stream:yes

Response:

RTSP/1.0200OK
CSeq:7
Session:12345678
Date:Wed,16Jul200813:01:25GMT

Example11:

InsomeolderAxisproducts,I-frameswererequestedusingRenewStream:yesintheheader.TondoutwhetherRenew-Stream
shouldbesentintheheaderorthebody,thefollowingmethodisrecommended.

21

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

SendarequestwithRequireandRenewStream:yesintheheader.

Request:

SET_PARAMETERrtsp://myserver/axis-media/media.ampRTSP/1.0
CSeq:7
Session:12345678
Require:com.axis.parameters-in-header
RenewStream:yes

Iftherequestissuccessful(response200OK),thestreamisrenewed.Else,theAxisproductrespondswith551Optionnot
supported(below)andRenewStreamshouldbesentinthebody.

Response:

RTSP/1.0551Optionnotsupported
CSeq:7
Session:12345678
Unsupported:com.axis.parameters-in-header
Date:Wed,16Jul200813:01:24GMT

SendasecondrequestwithRenewStream:yesinthebody.

Request:

SET_PARAMETERrtsp://myserver/axis-media/media.ampRTSP/1.0
CSeq:8
Session:12345678
Content-Type:text/parameters
Content-Length:19

Renew-Stream:yes

Successfulresponse.

Response:

RTSP/1.0200OK
CSeq:8
Session:12345678
Date:Wed,16Jul200813:01:25GMT

3.3RTSPOverHTTP

RTSPcanbetunnelledoverHTTP.Thismightprovenecessaryinordertopassrewallsetc.TotunnelRTSPoverHTTP,twosessions
aresetup;oneGET(forcommandrepliesandstreamdata)andonePOST(forcommands).RTSPcommandssentonthePOST
connectionarebase64encoded,buttherepliesontheGETconnectionareinplaintext.Tobindthetwosessionstogetherthe
AxisproductneedsauniqueID(conveyedinthex-sessioncookieheader).TheGETandPOSTrequestsareacceptedonboththe
HTTPport(default80)andtheRTSPserverport(default554).

Note

Forfurtherinformationinformationseehttp://developer.apple.com/quicktime/iceoe/dispatch028.html

Syntax:

http://<servername>/axis-media/media.amp

SupportedmethodsareGETandPOST.

22

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

Example12:

GETrequest.

Request:

GETaxis-media/media.amp?videocodec=h264&audio=0HTTP/1.0
x-sessioncookie:123456789

Response:

HTTP/1.0200OK
Content-Type:application/x-rtsp-tunnelled

Example13:

POSTrequest.ThereisnoresponsefromtheAxisproduct.

Request:

POSTaxis-media/media.amp?videocodec=h264&audio=0HTTP/1.0
x-sessioncookie:123456789
Content-Length:32767
Content-Type:application/x-rtsp-tunnelled

AfterthisrequesthasbeensentitispossibletosendRTSPrequestslikebelow.

DESCRIBErtsp://myserver/axis-media/media.amp?videocodec=h264RTSP/1.0
CSeq:14
User-Agent:AxisAMC
Accept:application/sdp

3.3.1NetworkParameters

ThefollowingparametersintheNetwork.RTSPgroupcontrolRTSPauthentication.

[Network.RTSP]

Parameter

AuthenticateOverHTTP

1.EvenifthecurrentdefaultbehaviorisnottorequireRTSPauthenticationwhentunnellingthroughHTTP,thiswillprobablychangeinthefuture.

ItisthereforestronglyrecommendedtoimplementRTSPDigestauthenticationforallclientsthatuseRTSPoverHTTP.

Default
values

1

no

ValidvaluesAccesscontrolDescription

yes
no

admin:read

PerformaRTSP
authenticationwhen
tunnelingRTSPoverHTTP.
yes=TheRTSPserver
requestsauthentication.
Thisismaderegardless
iftheHTTP-connectionis
authenticatedornot.
no=TheRTSPserverwill
notrequestauthentication.
Itisassumedthatthe
HTTP-connectionalreadyis
authenticated.

3.4ParameterSpecicationRTSPURL

RTSPAPIprovidesparametersforrequestingmediastreamswithspecicpropertiesandforimagesettings.Theparametersare
enteredintheRTSPURL.

23

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

Syntax:

rtsp://<servername>/axis-media/media.amp
[?<parameter>=<value>[&<parameter>=<value>...]]

ThefollowingparametersaresupportedforH.264,MPEG-4Part2andMotionJPEGstreams:

ParameterValidvaluesDescription

videocodech264

streamprofile

recordingid

resolution

audio0

camera

compression0…100

colorlevel

1

color

clock

date

text

textstring

textcolorblack

mpeg4

1

jpeg

AstringNameofasavedstreamprole

AstringNameofasavedrecording.

Productdependent

1

1...

1

quad

1

0…100

1

0
1

0
1

0
1

0
1

AnURL-encodedstring

white

Theselectedvideocodec.
Default:Productdependent;inorderof
priority:h264,mpeg4,jpeg.

Specifytheresolutionofthereturned
image.

Specifywhetheraudioshallbeavailable
inthestream(forcompatibilitywith
applicationswithoutaudiocontrol).

0=Noaudio.
1=Audio.

Default:1

Selectthevideosourceorthequad
stream.

Adjustthecompressionlevelofthe
image.Highervaluescorrespondto
highercompression,thatislowerimage
qualityandsmallerimagesize.
Note:Thisvalueisinternallymappedand
thereforeproduct-dependent.

Setthelevelofcolororgreyscale.

0=Greyscale.
100=Fullcolor.

Note:Thisvalueisinternallymappedand
thereforeproduct-dependent.

Enable/disablecolor.

0=Blackandwhite.
1=Color.

Show/hidethetimestamp.

0=Hide.
1=Show.

Show/hidethedate.

0=Hide.
1=Show.

Show/hidethetext.

0=Hide.
1=Show.

Setthetextshownintheimage.

Setthecolorofthetextshowninthe
image.

2

.

24

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

textbackgroundcolorblack

rotation0

textpos

overlayimage0

overlaypos=<int>,<int>
overlaypos=<int>x<int>

3

duration

nbrofframes

fps

pull=<bool>

white
transparent
semitransparent

90
180
270

0
1

1

Twounsignedintegers

Anunsignedinteger

Anunsignedinteger

Anunsignedinteger

0
1

Setthecolorofthetextbackground
shownintheimage.

Rotatetheimageclockwise.

1

Thepositionofthestringshowninthe
image.

0=Top.
1=Bottom.

Enable/disableoverlayimage.

0=Disable.
1=Enable.

Setthexandycoordinatesdeningthe
positionoftheoverlayimage.

Setthenumberofsecondsthevideowill
generateandpush.0=Unlimited.

SetthenumberofframestheAxisproduct
willgenerateandpush.0=Unlimited.

SettheframeratefromtheAxisproduct.
0=Unlimited.

OptionalparameterwhenusingPLAY.

1=Streamasfastaspossible.Because
thereceivingpartdeterminesthetransfer
rate,thisisonlyusefulwhentunneling
RTSPoverHTTP.
0=Disabled.Default.

1.Valuesareproductdependent.Checktheproductspecication.

2.Astreamproleisasetofvideostreamparameters(includingvideocodec)andisdenedintheHTTPAPIorthewebGUI.Supportedstream

prolenamesarestoredintheStreamProfile.S#.Nameparameters.Itispossibleoverrideparametervaluessavedinastreamprole
byspecifyingnewvaluesafterthestreamprole.Seesectionfordetails.

3.Obsolete.

H.264andMPEG-4Part2streamssupportthefollowingadditionalparameters:

ParameterValidvaluesDescription

videobitrate

Aninteger

Therate(inkbits/s)atwhichvideois
requested.

0=Variablebitrate.
>0=Constantbitratewiththegiven

targetbitrate.
Default:0

videomaxbitrate

Aninteger

Maximumbitrate(inkbits/s)forbitrate
control.
Default:0
0=Unlimited.

25

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

videobitratepriority

videokeyframeinterval

MotionJPEGstreamssupportthefollowingadditionalparameter:

ParameterValidvaluesDescription

squarepixel0

none
framerate

Aninteger

1

3.5ErrorMessagesRTSP

TheerrormessagesforRTSParedescribedinRFC2326.

3.6RTCP

RTPControlProtocol(RTCP)isimplementedaccordingtothestandardinRFC3550.

Theprioritywhenratecontrolisused.

CorrespondstotheGOVlengthsettingin
thewebGUI.
Default:32,butproductandcodec
dependent.

Enable/disablesquarepixel(aspectratio)
correction.Iftheparameterissetto1
theAxisproductwilladjuststheaspect
ratiotomakeitappearasintended.

26

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

4AlwaysMulticast

Alwaysmulticastmeansstartingamulticaststreamandlettingitruncontinuously.Enablingalwaysmulticastreducesthelatency
whenconnectingtoanAxisproduct.ThealwaysmulticaststreamsenabledontheAxisproductarepresentedbyaSessionDescription
Protocol(SDP).Usingthisinformationtheclientcanchoosetoconnecttotheservice.

4.1Prerequisites

4.1.1Identication

Property:Properties.API.HTTP.Version=3
Firmware:5.40andlater.

4.2SDP

Theclientmakesarequestaccordingtotheexamplebelow.Thecameraparameterspeciesthedesiredvideosourceonthe
Axisproduct.

TomakeaSDPrequestitisrequiredthatNetwork.RTP.R0.AlwaysMulticastVideo=yes.

4.2.1RequestSDPURL

Request:

http://myserver/axis-cgi/alwaysmulti.sdp?camera=1

4.2.2ResponseSDPURL

TheAxisproductrespondstherequestwithaSDP.TheSDPisprotectedbytheHTTPauthenticationoftheAxisproductandrequires
adminaccesscontrol.

Response:

v=0
o=-12844643630929041284464363092904INIP4axis
s=Multicastpresentation
e=NONE
t=00
a=range:npt=0.000000­m=video50000RTP/AVP96
c=INIP4239.225.149.138/0
b=AS:50000
a=framerate:25.0
a=transform:1,0,0;0,1,0;0,0,1
a=rtpmap:96H264/90000
a=fmtp:96packetization-mode=1;profile-level-id=420029;
sprop-parameter-sets=Z0IAKeKQFgJNgScFAQXh4kRU,aM48gA==

27

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

5StreamProles

Astreamproleisasetofvideostreamparameterssuitablefordifferentapplications,devicesorsituations.Streamprolescanbe
usedwhenretrievingavideostreamfromAxisproductsusingtheHTTPAPI,theRTSPAPIorthewebGUI.Allparametersthatcanbe
setinavideostreamrequestcanalsobesavedinastreamprole.

Afewstreamprolesareincludedatstartup.Theincludedstreamprolesaredesignedaccordingtobasicrequirementsandcan
becustomizedbyuserswithappropriateaccessrights.Userscaneasilycreatenewstreamproleswhenneeded.User-created
prolesmayalsoberemoved.

Streamprolesarealsousedtodenespecialimagestreamsettings,forexampleforinstantreplayandeventsrecording.

ThestreamproleAPIisanextensiontothevideostreamCGI’sStreamprolesparametersareadded,updated,listedandremoved
usingtheparametermanagementCGI(param.cgi).

5.1Prerequisites

5.1.1Identication

Property:Properties.API.HTTP.Version=3
Firmware:5.00andlater.

5.2CommonExamples

Example1:

Addanewstreamprole.Inthisexamplethenewproleisthe5thstreamprolesoitwillbereferredtoasStreamProfile.S4.

Request:

http://myserver/axis-cgi/param.cgi?action=add
&template=streamprofile
&group=StreamProfile

Response:

S4OK

Example2:

Addandcongureastreamproleinonerequest.Heretheproleisnamedmyprofile2andtheParametersstringis
videocodec=h264&resolution=4CIF&text=1&textstring=4CIF%20profile.See2.7ImageRequestArguments,

onpage13whatargumentsthatcouldbeusedintheParametersstring.

Note

CharactersintheParametersstringmustbeURL-encoded,so

resolution=CIF&text=1&textstring=CIF%20profilebecomes
resolution%3dCIF%26text%3d1%26textstring%3dCIF%2520profile

Theblankspaceisencodedas%20,theequalsign(=)as%3d,theampersand(&)as%26andthepercentsignisencoded
as%25.

28

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

Request:

http://myserver/axis-cgi/param.cgi?action=add
&template=streamprofile
&group=StreamProfile
&StreamProfile.S.Name=myprofile2
StreamProfile.S.Description=My%204CIF%20profile
&StreamProfile.S.Parameters=videocodec%3dh264
%26resolution%3d4CIF%26text%3d1%26textstring%3d4CIF%2520profile

Response:

S5OK

Example3:

Congureastreamprole.InthisexampletheproleisnamedmyprofileandtheParametersstringcontainsthefollowing
arguments:resolution=CIF,text=1andtextstring=CIFprole.See2.7ImageRequestArguments,onpage13what
argumentsthatcouldbeusedintheParametersstring.

Note

CharactersintheParametersstringmustbeURL-encoded,so

resolution=CIF&text=1&textstring=CIF%20profilebecomes
resolution%3dCIF%26text%3d1%26textstring%3dCIF%2520profile.

Theblankspaceisencodedas%20,theequalsign(=)as%3d,theampersand(&)as%26andthepercentsignisencoded
as%25.

Request:

http://myserver/axis-cgi/param.cgi?action=update
&StreamProfile.S4.Name=myprofile
&StreamProfile.S4.Description=My%20CIF%20profile
&StreamProfile.S4.Parameters=resolution%3dCIF%26text%3d1%26textstring%3dCIF%2520
profile

Response:

OK

Example4:

Listtheparametersofastreamprole.

Request:

http://myserver/axis-cgi/param.cgi?action=list&group=StreamProfile.S5

Response:

root.StreamProfile.S5.Name=myprofile2
root.StreamProfile.S5.Description=My%204CIF%20profile
root.StreamProfile.S5.Parameters=videocodec%3dh264
%26resolution%3d4CIF%26text%3d1
%26textstring%3d4CIF%2520profile

5.3StreamProleParameters

TheparametersintheStreamProfilegroupcontrolstreamprolesettings.

29

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

Note

Inordertocreateanewdynamicparameteradminoroperatoraccesscontrolisneeded.

[StreamProle.S#]

Template:streamprole

ParameterValidvaluesAccesscontrolDescription

NameA-Z

Description

Parameters

a-z
0-9

-,_

Astring.admin:read,write

<argument1>=<value1
>
&<argument2>=<valu­e2>
...

admin:read,write
operator:read,write
viewer:read

operator:read,write
viewer:read

admin:read,write
operator:read,write
viewer:read

Thenameofthestreamprole
usedintherequests.

Note:Eachprolemusthave
auniquename.

User-friendlydescriptionof
theprole.

Listofarguments.See2.7
ImageRequestArgumentsfor
completelist.

Note:Thecharactersmustbe
URL-encoded.

Note

The#isreplacedbyagroupnumber,forexampleStreamProfile.S5.Therstgroupnumbersarereservedfor
streamprolesincludedintheproduct

5.4MotionJPEGVideoRequest

SavedstreamprolesareconvenientwhenretrievingMotionJPEGvideostreamsthroughvideo.cgi.Thevalueofaparameter
savedinastreamprolecanbeoverriddenbyspecifyinganewparametervalueafterthestreamprofileargument.

Method:GET

Syntax:

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

Withthefollowingarguments:

ArgumentValidvaluesDescription

streamprofile=<string>

Additionalarguments

Example5:

Request,overHTTP,aMotionJPEGvideostreamconguredaccordingtothestreamprolemyprofile.

Nameofstreamprole

Seepage13foracompletelist.

Thenameofthestreamprole.Supported
streamprolenamesarestoredinthe

StreamProfile.S#.Name

parameters.

30

VideoStreamingAPI

ThisdocumentiscopyrightprotectedandisthepropertyofAxisCommunicationsABandmaynotbecopied,reproducedordistributedinanywaywithout
thepriorwrittenconsentofAxisCommunicationsAB.

Request:

http://myserver/axis-cgi/mjpg/video.cgi?&streamprofile=myprofile

5.5RTSPRequest

SavedstreamprolesarealsoconvenientwhenrequestingvideostreamsusingRTSP.Thevalueofaparametersavedinthestream
prolecanbeoverriddenintheRTSPrequestbyspecifyinganewvalueafterthestreamproleargument.

Syntax:

COMMANDrtsp://<servername>/axis-media/media.amp
?<argument>=<value>[&<argument>=<value>...]RTSP/1.0
Headerfield1:val1<CRLF>
Headerfield2:val1<CRLF>
...
<CRLF>

[Body]

Withthefollowingarguments:

ArgumentValidvaluesDescription

streamprofile=<string>

Additionalarguments

Example6:

StreamprolesinRTSPrequests.Thevalueofaparametersavedinthestreamprolecanbeoverriddenbyspecifyinganew
parametervalueafterstreamprofile.Here,myprofile2(denedabove)isusedbuttheresolutionischangedto640x480.

Request:

DESCRIBErtsp://myserver/axis-media/media.amp?
streamprofile=myprofile2&resolution=640x480RTSP/1.0
CSeq:0
User-Agent:AxisAMC
Accept:application/sdp

Nameofstreamprole

Seepage23foracompletelist.

Thenameofthestreamprole.Supported
streamprolenamesarestoredinthe

StreamProfile.S#.Name

parameters.

31

VAPIX®version3
VideoStreamingAPI
©AxisCommunicationsAB,2008-2013

Ver.M4.2
Date:July2013
PartNo.52937