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