Camera Objects

The SAFR SDK comes with objects that make it easy to work with USB, IP, and ONVIF cameras. It also includes a generic video player which can play back video as well as stream HTTP and RTSP videos over the network. It also includes a video view which makes it easy to display a video stream on screen.

Camera

Camera is an abstract base class which represents a camera device and its properties. There are concrete subclasses for specific types of cameras: USB cameras, IP cameras, and ONVIF cameras. A USB camera is a camera that is directly connected to the computer and discovered by the operating system. An IP camera is a camera which makes a video stream available which can be connected to via a public (and usually unsecured) HTTP or RTSP URL. An ONVIF camera is a camera which implements the ONVIF camera discovery and control standard. The CameraManager uses the ONVIF protocol to discover ONVIF cameras and the OnvifCamera class uses the ONVIF protocol to acquire information about the camera and to initiate a video stream.

You acquire camera objects by asking the CameraManager for them. The CameraManager knows how to discover and manage cameras.

A camera has properties such as its name and a set of available video formats. Some of those properties may be configurable for some types of cameras and read-only for other types. For example, the name of a camera is configurable for IP cameras but read-only for ONVIF cameras because the name of the camera in this case is only configurable via the web-UI provided by the camera software.

Every camera has a globally unique identifier. This identifier is guaranteed to remain stable and may be persisted. You can use this identifier to associate your own configuration information with a camera.

You create a video stream from a camera by asking the camera for a capture session via the CreateCaptureSession() function. This function takes a video profile which specifies the video resolution and frames per second that the video stream should have. Note that some cameras may allow you to create more than one capture session for a given video profile and some may allow only one active capture session per video profile.

Use the DefaultProfile property to get the default video profile of a camera. The default profile is usually a 1080p profile or close to it. Use the Profiles property to get the full list of available profiles. You can iterate through this list of profiles to find one that most closely matches what you're looking for. You can then create a capture session with this profile.

Once you've created a capture session you should register event handlers on the capture session object to receive video frames and errors. You can then start the capture session by setting its Capturing property to true. You can pause/stop capturing at any time by setting Capturing to false.

IPCamera

An IP camera object represents a type of camera which allows you to stream a video from a fixed and publicly accessible URL. This kind of cameras can't be automatically discovered. You must instead explicitly create this kind of camera and it to the camera manager by calling the camera manager AddCamera() function with the correct video stream URL.

OnvifCamera

An ONVIF camera object represents a camera which implements the ONVIF camera discovery and managed standard.

An ONVIF camera must be authenticated before you're allowed to access the available video profile information and before you're able to create a capture session.

You authenticate an ONVI camera after it has been discovered by the camera manager and before you create a capture session. Invoke the Authenticate() function on the camera object with the correct camera credentials. The camera will start the authentication process and invoke the callback that you provided to the Authenticate() function once authentication is complete. The callback is invoked with an appropriate error if authentication was unsuccessful.

USBCamera

A USBCamera camera object represents a camera which is directly connected to the computer and discovered by the operating system. Examples of such cameras are cameras which are connected via USB.

CaptureSession

A video capture session is created by invoking the CreateCaptureSession() function on a camera object. It represents a video stream with a specific video resolution and frames-per-second setting. A capture session is created in the paused state. Set its Capturing property to true to start the capture session and set it to false to pause or stop the capture session.

The Accelerator argument of the CreateCaptureSession() function specifies the object providing GPU acceleration of video decoding as follows:

Element Description
null No GPU acceleration.
RealNetworks.CameraKit.Accelerator.Shared Use the GPU representing primary display.
RealNetworks.CameraKit.Accelerator.Create(RealNetworks.CameraKit.Adapter) Use a specific GPU, represented by Adapter. (RealNetworks.CameraKit.Adapter.All lists all available adapters).

You should register a frame event handler before starting the capture session. Do this by assigning your event handler function to the DidDecode event property. The capture session invokes the DidDecode event for every decoded video frame. You can get the video frame from the event argument.

You should register an event handler to the DidDetectError event handler property to be notified of capture session errors.

CameraManager

The camera manager is responsible for the discovery of cameras and it allows you easy access to the default camera for a camera position.

You trigger camera discovery by invoking the TriggerDiscovery function. Camera discovery operates asynchronously. You should invoke this function at least once at application startup and you may invoke it at additional times. Generically this function should be invoked any time that the list of available cameras may change. (e.g. every time your application becomes the active application)

You should register an event handler with the DidEndDiscovery property. The camera manager will invoke this event handler every time a camera discovery session has completed. This event handler is invoked with the list of all the cameras that are known to the camera manager at this moment in time. So this list includes both newly and previously discovered cameras.

The camera manager allows you to look up a camera by its unqiue identifier and it allows you to get the default camera for a camera position. A camera position indicates where a camera is located relative to the user. For example there is a camera position for the "front camera" and another one for the "back camera". A front camera is a camera which typically faces the user while a back camera is a camera which faces away from the user.

VideoPlayer

VideoPlayer allows you to play back a video file or a HTTP/RTSP video stream.

Note: The video player supports video streams only; it does not support audio streams.

Do the following:

The video player enforces the video clock if the URL points to a video file, but it does not enforce the video clock if the URL points to a HTTP or RTSP video stream. In this case, the video player decodes video frames as fast as they arrive from the camera. It does this to minimize the video playback latency.

VideoView

A video view displays the video frames from a capture session or video player on the screen. The video timing is provided by the capture session or video player.

Note: The video view itself does not impose video timing. It immediately displays a video frame when you set it on the view.

See Also