Aimetis Symphony SDK User Guide
Copyright Aimetis 2013
Overview




The latest SDK user guide is available here:
http://www.aimetis.com/Library/Downloads/SDK%20User%20Guide.docx
The Aimetis Symphony SDK enables interaction with Symphony from custom applications.
There are sample applications included for the most common use cases.
Symphony Client uses these same interfaces ensuring quality and feature completeness.
Requirements





Software should be developed against .NET 2.0 or later.
If the customer wants to access Symphony from alternate platforms, then they need to develop
their own layer that provides this interface. Ported implementations of .NET may work (such as
Mono), but the referenced .NET libraries link to Windows style DLLs which would require deeper
platform equivalence.
The development IDE should be Visual Studio 2005 or later. It is known working in Visual Studio
2010.
The application should be written in C#, but other managed languages may work as well.
Other .NET based languages may work (customers have reported Visual Basic working), but C# is
recommended.
Developer should be familiar with Aimetis Symphony.
Developer should be familiar with C# development to understand the samples.
Quick Start
1. Download and install the Symphony SDK:
http://aimetis.com/Xnet/Downloads/Files.aspx?P=development%2fSDK
2. Start bin\LiveStreamTest.exe to see live video from a Symphony Farm.
Contact
Questions and comments can be sent to support@aimetis.com
Interfaces




Live and historical video streaming/viewing
Live video analytics XML metadata streaming
Symphony event stream
Web Service
Over 100 webservice calls in the following categories:
o Access Control
o Alarms
o Analog capture card management
o Backup/Restore
o Bookmarks
o Carousels
o Device
o Device Groups
o Events
o Farm
o Footage management
o JPGs
o Map
o Plug-ins
o PTZ
o Rules
o Search
o Security
o Service management
o Speaking and playing audio
o Timeline
o User Groups
o Users
o Video Analytics
o Video settings
o Video Wall
Functionality to Sample Code Mapping








Basics
o Farm connectivity
 How to connect to a farm (NotificationMonitorExample). Other methods of
connecting (demonstrated in other samples) are not recommended.
 How to get a list of cameras in a farm (SymphonyFarmTest)
 How to get a list of servers in a farm (SymphonyFarmTest)
o Video
 How to connect to and render live video (LiveStreamTest)
 How to connect to and render historical video (LiveStreamTest)
 How to get a historical JPG (SymphonyFarmTest)
 How to navigate by frame/activity/alarm (SymphonyFarmTest)
o PTZ and camera control
 How to control PTZ on a video device (SymphonyFarmTest)
 How to load guard tour locations (SymphonyFarmTest)
 How to go to a specific guard tour location (SymphonyFarmTest)
 How to save a location to a preset (SymphonyFarmTest)
 How to set PTZ speed (SymphonyFarmTest)
 How to focus cameras in and out (SymphonyFarmTest)
Events
o How to trigger an alarm (AddAlarmToCamera)
o How to listen for alarms (AlarmHandlerExample)
o How to pull JPEGs when alarms occur (AlarmHandlerExample)
o How to get a list of alarms (LiveStreamTest)
o How to mark an alarm (LiveStreamTest)
o How to listen for farm events (NotificationMonitorExample, NotificationMonitors)
Farm settings
o How to retrieve many farm settings (WebService)
o How to execute a web service method (WebServiceConsole)
o How to get a list of servers in a farm (SymphonyFarmTest)
Recording
o How to start/stop recording (SymphonyFarmTest)
Symphony Client Control
o How to change what is displaying in a Symphony Client video panel (VideoWall)
Reports
o How to get a heatmap (GetDensityImageJpg)
Security
o How to change the currently active security profile (SetActiveProfile)
o How to add and remove users (UserManagement)
Video Wall

o How to switch a video wall panel to a camera or a historical view (VideoWall)
Video Analytics
o How to get live XML metadata from a running analytics engine (XMLStream)
o Plugging 3rd party video into a Symphony analytics engine
 How to analyze video in Symphony from a 3rd party video system
(AlgorithmIntegration)
Shows how to push decompressed video frames through a Symphony analytics
engine.
 How to load a Symphony UI component in a 3rd party application (PluginHost)
This shows how to load the analytics and rule configuration UI components in a
3rd party application. These components export settings as XML which are
needed to initialize the analytics and rule engines.
o Plugging a 3rd party video analytics engine into Symphony
 How to incorporate your own analytics engine (AlgoSample)
This enables a developer to write their own vision code and have it run against
any Symphony video source. It demonstrates both the analytics engine and the
rule engine.
 How to incorporate your own rules engine (AlgoSample, TestRuleEngine)
Symphony Managed Libraries used by the SDK



The following managed DLLs are used directly by SDK samples
o Aimetis.Connectivity.dll
 Deprecated library for connecting to servers
o BaseLibCS.dll
 BaseLibCS.Communication.ServerConnectionManager for client server connectivity
 BaseLibCS.AiraWS.Signals for Web Service interface
 BaseLibCS.CameraMessageStruct for structure definitions
 BaseLibCS.Utils.MulticastMessage for constants
o Core.dll (source part of SDK)
 Aimetis.Symphony.SDK.SDKFarm for farm connectivity and event stream
notifications
o Farm.dll
 DeviceModel.Client for client side device operations and information
 DeviceModel.Server for server side device operations and information
o Internationalization.dll
 Aimetis.Symphony.Internationalization.Translator for language translation into all
Symphony supported languages.
o NotificationMonitors.dll (source part of SDK)
 Interface to the event stream that comes from Symphony
The following managed DLLs are dependencies of the above DLLs and likely do not need to be used
by your code directly. However they may need to be added as references to your project. If they do
need to be added, the compiler will fail with a message stating what reference needs to be added.
o Aimetis.Symphony.Common.dll
o DeviceModel.Dio.dll
o DeviceModel.Security.dll
o Farm.Security.dll
o SecurityLib.dll
DLLs that enable access to video streaming
o AxVideoRecvCtrl.dll wraps VideoRecvCtrl.dll
o BaseIDL.dll is a set of COM interfaces that aid in streaming video
Symphony Media Streaming Libraries used by the SDK
AxVideoRecvCtrl.dll -> AxVideoRecvCtrl
Simple interface to viewing control used by web and SDK clients.
Functions
public virtual void Connect(uint iP, ushort port, string user, string pass, long historicalTime);
public virtual void Connect2(string host, ushort port, string user, string pass, long
historicalTime);
public virtual void Connect3(uint iP, ushort port, string user, string pass, int historicalTime,
int historicalMS);
Connects a control to a live or historical video stream.
iP: A 4 byte unsigned int of the IP to connect to (see GetAddr in LiveStreamTest).
port: The port to connect to.
user: The username to authenticate with
pass: The password to authenticate with
historicalTime: Use 0 to connect to live, otherwise specify the historical time in number of
seconds since GMT 1970.
historicalMS: Use 0 to connect to live, otherwise specify the historical time in number of
seconds since GMT 1970.
public virtual void Destroy();
Disconnects and frees memory for a control.
public virtual long GetLastMediaTime();
Returns the time of the last frame rendered by the control in number of seconds since GMT 1970.
public virtual void GetLastMediaTime3(out int pTime, out int pMS);
pTime: pointer in memory to store the number of seconds since GMT 1970 for the last frame
decompressed.
pMS: pointer in memory to store the milliseconds for the last frame decompressed.
public
public
public
public
public
virtual
virtual
virtual
virtual
virtual
void
void
void
void
void
Init();
SetDecorations(int flags);
SetRegionalSettings(int iTZOffsetSeconds, int b24HourClock, int iDateFormat);
StartVideo();
StopVideo();
Events:
public event EventHandler FrameArrived;
A frame has been decoded and rendered. Useful for counting or call GetLastMediaTime3 within a
handler for this event to know the time of the current frame.
public event EventHandler GraphInited;
The directshow graph has been successfully connected and initialized.
public event EventHandler GraphStarted;
The directshow graph has begun running (connecting to camera, etc.).
VideoRecvCtrlLib.dll -> IVideoRecvCtrl
Full featured interface to viewing control used by SDK and Symphony client.
Functions
void BeginInitGraph();
void ConnectGraph();
void ConnectGraphAuth(string user, string pass);
void DestroyGraph();
void DisconnectGraph();
void GetAddr(out uint IP);
void GetDimensions(out int width, out int height);
void GetDimensions2(out int width, out int height, int bScale);
string GetLastError();
void GetLastImage(out int iWidth, out int iHeight, IntPtr pBufferOut, ref int
pBufferSize);
void GetMode(out GraphMode gmode, out string modeparams);
void GetRegionalSettings(out int ipTZOffsetSeconds, out int bp24HourClock,
out int ipDateFormat);
void InitGraph();
int IsConnected();
int IsRunning();
void PutOptionsOnNetaddr(string sOptions);
void SetCameraType(int type, float pan, float tilt, float rotation);
void SetDecorations(int flags);
void SetDecorationText(string text, int x, int y);
void SetDewarpView(int flag, float pan, float tilt);
void SetDewarpView2(int flag, int ptzType, float pan, float tilt, float
zoom);
void SetDigitalTracking(int enabled);
void SetFrameRate(int decreaseFPS, int framerate);
void SetFrameRateD(int decreaseFPS, double framerate);
void SetMode(GraphMode gmode, string modeparams);
void SetMultiStreamRatio(double x, double y);
void SetRegionalSettings(int iTZOffsetSeconds, int b24HourClock, int
iDateFormat);
void SetRenderingRectangleD(double x, double y, double width, double height);
void SetSound(int iType);
void SetStreamNumber(int streamNumber);
void SetVideoRenderMode(int iOption);
void SetViewPoint(float pan, float tilt, float zoom);
void SetZoomBox(double x, double y, double width, double height, int type);
int ShouldAbandonControl();
void Start(int supportsAuth);
void Stop();
Events
None
How to Add Video Streaming to a Project
1.
2.
3.
4.
5.
6.
7.
Open the design view of the form where you want to add the control
From the Tools menu, select "Add/Remove Toolbox Items..."
Click on the COM Components tab
Scroll down and check "VideoRecvCtrl Control"
Click OK
The Active X control should now appear in the toolbox, at the end of the Windows Forms section.
Drag it onto the design view where you want it.
Requirements
.NET framework 2.0 is required at run time.
FAQ
JPEGs
1) How to get a JPEG
a. The recommended (simplest) approach is to use the DeviceModel.Client.CCamera
GetJPEGImage function to get a JPEG. This functions calls the AiraWS functions below.
b. The different web service GetJPEG* functions in AiraWS:
i. GetJPEG generates the JPEG and returns an URL to it. The other GetJPEG* functions
return the bytes of the JPEG.
ii. GetJPEGImage gets a JPEG bytes for a specified time and camera.
iii. GetJPEGImage3 extends GetJPEGImage by allowing you to send params for the
decorations
iv. GetJPEGImage4 extends GetJPEGImage3 by allowing you to send params for the
font used on the image.
2) How to set decoration options when getting a JPEG
CCamera.GetJPEGImage, GetJPEGImage3, GetJPEGImage4 can take a stuffed decoration parameter.
You can create it like this:
DecorationOptions decorations = new DecorationOptions(15, 0, true, 0);
// Pass decorations. EncodedDecorationOptions to GetJPEG* functions
// You will want to use the following DecorationOptions constructor
public DecorationOptions(int decorations, int dateFormat, bool in24HourNotation, uint
streamIndex)
{
// BITWISE OR together the following to select decoration
// 1 = rectangles.
// 2 = messages.
// 4 = time.
// 8 = paths.
_rawDecoration = decorations;
// SET to one of the following
// 0 = yyyy/MM/dd
// 1 = dd/MM/yyyy
// 2 = MM/dd/yyyy
_dateFormat = dateFormat;
// True for 24 hour time format. False for 12 hour time format.
_in24HourNotation = in24HourNotation;
// 0 based stream number. The Symphony Client UI is 1 based.
_streamIndex = streamIndex;
}
3) How to get a live JPEG if recording is set to never
a. If tracker is running analytics (in which case it needs to decompress video), then recording is
not required to get a live JPEG. If you pass a date-time to the functions above with a year
less than 1990, the request will go to trackerapp in which case trackerapp will try to
generate the JPEG.
b. Our MobileBridge (RESTful webservice API used by our mobile clients) actually does exactly
what you need (can get JPEGs for live video whether or not video is being recorded), but
that is not open sourced and the API is not public.
c. This is another approach that could work:
i. Set a camera to record never, and set the rule pre and post record times (defaults
are shown below).
ii. Add a rule.
iii. Turn Raise Alarm off since you probably will not these to register as alarms in the
system (alarms will not appear in the timeline and will not appear in the alarm log)
iv. When you want an image, cause the rule to break (use the AddAlarmToCamera SDK
sample). This will cause video to be stored. Now request a JPEG for the current
time.
d. If Symphony support edge storage with the camera (currently only AXIS), and edge storage
is setup. Then if recording is set to never, NetSendHist (a service that supplies historical
JPEGs) will try to pull the JPEG directly from the camera.