CameraStreamer (v3.1)

Hints:

  • In case of multiple CameraStreamer instances usage it's generally advised to mute audio on all or all except one CameraStreamer instances.
  • In iOS the CameraStreamer constructor takes CALayer parameter (most commonly obtained via view.layer property).
  • In Android the CameraStreamer constructor takes Surface parameter (most commonly obtained via TextureView::getSurfaceTexture() method).
  • In Android take takeSnapshot() method is absent because the video decoder works directly with passed Surface object and therefore doesn't have access to raw frames. There is an easy and convenient way to take snapshot though: TextureView::getBitmap() method (the same view that holds the Surface from the previous step).

class CameraStreamer
CameraStreamer(Surface surface);

Constructs CameraStreamer instance.

release();

Android specific: releases unnecessary resources.

weak CameraStreamerDelegate delegate;

Indicates object which will receive and process callbacks.

StreamerItem currentItem;

Indicates the current item of the streamer.

CameraStreamerRenderMode renderMode;

Defines how the video is displayed within Surface bounds rect.

Bool muteAudio;

Indicates whether or not audio output of the player is muted. Only affects audio muting for the player instance and not for the device.

Float rate;

Indicates the desired rate of playback; 0.0 means "paused", 1.0 indicates a desire to play at the natural rate of the current item.

readonly CameraStreamerStatus status;

Indicates readiness of streamer to be used for playback.

readonly MobileSDKError failureReason;

If status is failed, this property describes the error that caused the failure.

readonly CameraStreamerPlaybackState playbackState;

Indicates whether playback is currently paused indefinitely, suspended while waiting for appropriate conditions, in progress or reached end of media data.

readonly CameraStreamerAudioStreamingState audioStreamingState;

Indicates whether audio streaming session is currently not streaming, being preraped for streaming or actually streaming.

readonly MobileSDKError audioNotStreamingReason;

If audioStreamingState becomes notStreaming unexpectedly (not as result of a -stopAudioStreaming method call), this property describes the reason.

readonly Double currentTime;

Returns the current time of the playback within [0 ... duration] range for footage stream or zero for live stream.

seekTo(Double time);

Moves the playback cursor within [0 ... duration] range.

stepBy(Int frameCount);

Pauses streamer and moves player's current item's current time forward or backward by the specified number of frames.

startAudioStreaming();

Starts audio streaming session.

stopAudioStreaming();

Stops audio streaming session.

takeSnapshot();

iOS specific: Generates a snapshot for a stream at current time.

protocol CameraStreamerDelegate
@optional onStatusChanged(CameraStreamerStatus newStatus);

Will get called when the status of streamer has been changed.

@optional onPlaybackStateChanged(CameraStreamerPlaybackState newState);

Will get called when the playback state of streamer has been changed.

@optional onAudioStreamingStateChanged(CameraStreamerAudioStreamingState newState);

Will get called when the audio streaming state of streaming has been changed.

@optional onCurrentItemStatusChanged(StreamerItemStatus newStatus);

Will get called when the status of current item has been changed.

@optional onCurrentItemDurationChanged(Double newDuration);

Will get called when the duration of current item has been changed.

@optional onSnapshotTaken(Byte[] snapshot, Double snapshotTime);

Will be called when snapshot has been generated.

enum CameraStreamerStatus

case unknown;

Indicates that the status of the streamer is not yet known because it has not tried to load new media resources for playback.

case readyToPlay;

Indicates that the streamer is ready to play StreamerItem instance.

case failed;

Indicates that the streamer can no longer play StreamerItem instance because of an error. The error is described by the value of the failureReason property.

enum CameraStreamerPlaybackState

case paused;

This state is entered 1) upon receipt of a -pause message or -setRate: message with a value of 0.0, 2) when a change in overall state requires playback to be halted, such as when an interruption occurs on iOS or 3) when the streamer has no item to play, i.e. when the receiver's currentItem is nil.

In this state, playback is paused indefinitely and will not resume until 1) a subsequent -play message is received or 2) a -setRate: message with a non-zero value for rate is received and sufficient media data has been buffered for playback to proceed.

case buffering;

This state is entered when 1) the playback buffer becomes empty and playback stalls in playing state, 2) when rate is set from zero to non-zero in paused state and insufficient media data has been buffered for playback to occur.

In this state, the value of the rate property is not currently effective but instead indicates the rate at which playback will start or resume.

case playing;

In this state, playback is currently progressing and rate changes will take effect immediately. Should playback stall because of insufficient media data, playbackState will change to buffering state.

case ended;

This state is entered when playback reaches end of media data. Subsequent -play: or setRate: with non-zero value messages will be ignored, -seekTo:, -stepBy:, -pause: or setRate: with zero value messages will change playbackState to paused state.

enum CameraStreamerAudioStreamingState

case notStreaming;

This state is entered 1) upon receipt of a -stopAudioStreaming message or 2) when a change in overall state or some other reason requires streaming to be halted.

case preparing;

This state is entered upon receipt of a -startAudioStreaming message if previous value is CMCameraStreamerAudioStreamingStateNotStreaming.

case streaming;

In this state, audio streming is currently progressing.

enum CameraStreamerRenderMode 

case fillBounds;

Specifies that the video should be stretched to fill the layer’s bounds.

case aspectFit;

Specifies that the streamer should preserve the video’s aspect ratio and fit the video within the layer’s bounds.

case aspectFill;

Specifies that the streamer should preserve the video’s aspect ratio and fill the layer’s bounds.

class StreamerItem

static StreamerItem createItem(Long cameraId);

Initializes an instance StreamerItem with given cameraId.

static StreamerItem createItem(Long cameraId, Long recordingId);

Initializes an instance StreamerItem with given cameraId and recordingId.

readonly Long cameraId;

An id of camera for which live or footage stream should be played.

readonly Long recordingId;

An id of recording to be played.

readonly StreamerItemStatus status;

Indicates if the item is ready to be played.

readonly MobileSDKError failureReason;

If status is failed, this property describes the error that caused the failure.

readonly StreamerItemCapabilitiesMask capabilitiesMask;

Indicates playback capabilities of item.

readonly Double duration;

Indicates the duration of the item.

enum StreamerItemStatus

case unknown;

Indicates that the status of the streamer item is not yet known because it has not tried to load new media resources for playback.

case ready;

Indicates that the streamer item is ready to be played. At this moment metadata (capabilitiesMask, duration) can be processed.

case failed;

Indicates that the streamer item can no longer be played because of an error. The error is described by the value of the failureReason property.

enum StreamerItemCapabilitiesMask

case none = 0;

Indicates that item has no playback capabilities. Usually means that item represents live streaming.

case canSeek = 1 << 0;

Indicates whether the item suports seeking. Call CameraStreamer's -seekTo: method to seek stream to requested time.

case canSpeedPlay = 1 << 1; 

Indicates whether the supports speed play. Rate can be changed by setting positive value to CameraStreamer's rate property.

case canStep = 1 << 2;

Indicates whether the item supports stepping. Call CameraStreamer's -stepBy: method to step by requested amount of frames.

case canStreamAudio = 1 << 3;

Indicates whether the item supports audio streaming. Audio streaming session can be managed by calling CMCameraStreamerInterface instance's -startAudioStreaming, -stopAudioStreaming methods.