Flussonic Watcher Documentation

Watcher API for iOS Apps

This page contains the description of Mobile Watcher API for iOS.

Classes

Enumerations

Protocols

Structures

Class FlussonicWatcherView

public class FlussonicWatcherView : UIView, FlussonicWatcher, NibLoadable, FlussonicPlayerAdapterDelegate, TimelineToPlayerDelegate

Presents a single camera view player and controls.

A camera view will try to take all screen space possible.

Can support no more than four simultaneous instances due to hardware restrictions (this information requires verification).

delegate: FlussonicWatcherDelegateProtocol?

weak public var delegate: FlussonicWatcherDelegateProtocol?

The delegate will be notified about player events.

alertDelegate: UIViewController?

weak public var alertDelegate: UIViewController?

The delegate will be used to present alert views.

downloadRequestListener: FlussonicDownloadRequestListener?

weak public var downloadRequestListener: FlussonicDownloadRequestListener?

The delegate will be notified about video download request events.

bufferingListener: FlussonicBufferingListener?

weak public var bufferingListener: FlussonicBufferingListener?

The delegate will be notified about buffering events.

updateProgressEventListener: FlussonicUpdateProgressEventListener?

weak public var updateProgressEventListener: FlussonicUpdateProgressEventListener?

The delegate will be notified about update progress events.

allowDownload: Bool

public var allowDownload: Bool { get set }

Sets the possibility of downloading a portion of video stream as a separate clip.

startPositionDate: Date?

public var startPositionDate: Date?

If set on init, the instance will try to start playing from this position, if possible.

Initializing

(Player initializing) configure(withUrl url: URL, playerAdapter adapter: FlussonicPlayerAdapterProtocol)

public func configure(withUrl url: URL, playerAdapter adapter: FlussonicPlayerAdapterProtocol)

Configures a view with an URL.

Parameters:

(Player initializing) configure(withCameraItem cameraItem: CameraItem, playerAdapter adapter: FlussonicPlayerAdapterProtocol?)

public func configure(withCameraItem cameraItem: CameraItem, playerAdapter adapter: FlussonicPlayerAdapterProtocol?)

Configures a view with a cameraItem without specifying the session token.

Parameters:

Playing an archive from the specified time

mediaPlayerTimeChanged(oldTimeValue: Double, newTimeValue: Double)

public func mediaPlayerTimeChanged(oldTimeValue: Double, newTimeValue: Double)

Undocumented.

The FlussonicPlayerView protocol

setAllowDownload(allowDownload: Bool)

public func setAllowDownload(allowDownload: Bool)

Enables or disables downloading of a portion of video stream as a separate clip.

Parameters:

  • allowDownload: sets a value.

public func setStartPosition(dateTimeInSecs: Int64)

public func setStartPosition(dateTimeInSecs: Int64)

Sets the starting position.

An instance of FlussonicWatcherView will try to start playing from this position, if possible.

Parameters:

  • dateTimeInSecs: the position to start from, Unix timestamp.

pause()

public func pause()

Pauses the currently played stream.

resume()

public func resume()

Resumes the current stream. Live stream jumps to live (playing mode), and an archive resumes playing from the current position in archive playing mode.

seek(seconds: TimeInterval)

public func seek(seconds: TimeInterval)

Tries to play video starting from the specified time.

Parameters:

  • seconds: time to jump to, Unixtime.

screenshotCaptured: (UIImage) -> ()

public var screenshotCaptured: (UIImage) -> ()

This block will be called on screenshot captured.

captureScreenshot(destUrl: URL)

public func captureScreenshot(destUrl: URL)

Captures a screenshot of the currently played stream.

Parameters:

  • destUrl: the URL to save the screenshot image to.

setBufferingListener(bufferingListener: FlussonicBufferingListener?)

public func setBufferingListener(bufferingListener: FlussonicBufferingListener?)

Sets a listener for buffering events.

Parameters:

  • bufferingListener: The instance to be notified.

setDownloadRequestListener(downloadRequestListener: FlussonicDownloadRequestListener?)

public func setDownloadRequestListener(downloadRequestListener: FlussonicDownloadRequestListener?)

Sets a listener for download request events.

Parameters:

  • downloadRequestListener: The instance to be notified.

public func setUpdateProgressEventListener(updateProgressEventListener: FlussonicUpdateProgressEventListener?)

public func setUpdateProgressEventListener(updateProgressEventListener: FlussonicUpdateProgressEventListener?)

Sets a listener for update progress events.

Parameters:

  • updateProgressEventListener: The instance to be notified.

getCurrentUtcInSeconds() -> Int64

public func getCurrentUtcInSeconds() -> Int64

The current time where the player is now playing the video.

getPlaybackStatus() -> Int

public func getPlaybackStatus() -> Int

Current playback status.

getSpeed() -> CGFloat

public func getSpeed() -> CGFloat

Current player speed.

getAvailableStreams() -> Array<StreamItem>

public func getAvailableStreams() -> Array<StreamItem>

Returns information about tracks in available multi-bitrate streams.

getCurrentStream() -> StreamItem?

public func getCurrentStream() -> StreamItem?

Returns information about tracks in the currently played multi-bitrate stream.

setNetworkQualityThresholdCount(count: Int)

public func setNetworkQualityThresholdCount(count: Int)

The number of interrupts to the player due to a bad network connection after which the player automatically switches to a low bitrate video stream.

Parameters:

  • count: The maximum number of interruptions to the player

setShowDebugInfo(newValue: Bool)

public func setShowDebugInfo(newValue: Bool)

Shows or hides debug info in the top right corner of the player window.

Parameters:

  • newValue: a new value

Class PreviewMp4View

public class PreviewMp4View : UIView, NibLoadable

Loads a clip with the duration of a single-frame clip and shows the decoded image as a preview image in the player.

Loaded images will be cached using their URL as a key.

In case of an error, shows the picture of a broken camera.

statusListener: PreviewMp4ViewStatusListener?

public weak var statusListener: PreviewMp4ViewStatusListener?

The listener will be notified upon status change.

status: PreviewMp4StatusEnum { get set }

public private(set) var status: PreviewMp4StatusEnum { get set }

The current status of preview from a camera.

init(frame: CGRect)

public override init(frame: CGRect)

Undocumented.

init?(coder: NSCoder)

public required init?(coder: NSCoder)

Undocumented.

(Initializing) configure(withUrl url: URL, cacheKey: String?)

@objc(withUrl:cacheKey:)
public func configure(withUrl url: URL, cacheKey: String?)

Configures a view with URL.

Loading will start immediately.

Successfully loaded image will be cached using the URL as a key.

Parameters:

  • url: the URL with a user session:

    (protocol)://(session)@(server):(port)/(camera_name)/preview.mp4

(Initializing) configure(withCameraItem cameraItem: CameraItem, cacheKey: String?)

public func configure(withCameraItem cameraItem: CameraItem, cacheKey: String?)

Configures a view with a cameraItem.

Loading will start immediately.

A successfully loaded image will be cached using cacheKey as a key.

Parameters:

reset()

@objc
public func reset()

Resets a preview view if the view if reused.

Used in UITableViewController, where when the user scroll through the list, old views are reused to display new preview images.

The reset() method cancels the loading of the preview image (if it is not already loaded) and resets the view state.

A preview download currently in progress will not be canceled, and the preview image will be cached on successful download.

cleanCache()

@objc(cleanCacheForKey:)
public func cleanCache()

Clears the all previews cache.

A preview download currently in progress will not be canceled, and the preview image will be cached on successful download.

cleanCache(for cacheKey: String)

public func cleanCache(for cacheKey: String)

Clears the cache of URL previews.

A preview download currently in progress will not be canceled, and the preview image will be cached on successful download.

layoutSubviews()

override public func layoutSubviews()

Undocumented.

Class ProgressEvent

public class ProgressEvent : NSObject

The class is used to notify a delegate about update progress events.

currentUtcInSeconds: Double

public private(set) var currentUtcInSeconds: Double

Current UTC time in seconds.

playbackStatus: UniversalStatus

public private(set) var playbackStatus: UniversalStatus

Current playback status.

playbackStatusString: String

public private(set) var playbackStatusString: String

Current playback status description.

speed: Double

public private(set) var speed: Double

Current player speed.

Class DateTimeViewController

public class DateTimeViewController : UIViewController

The class provides a way to define date and time. DateTime ViewController is a calendar that allows the user to select the date and time to start playing video from a DVR archive.

startDate: Date

public var startDate: Date

The start date of an interval to play.

If the start date is in the future, it will be reduced to current date and time.

onCompletion: ((Date?) -> Void)

public var onCompletion: ((Date?) -> Void)

The block will be called on dismissing the controller.

Parameters:

  • Return Value: date or nil if canceled.

instance() -> DateTimeViewController?

public static func instance() -> DateTimeViewController?

The function loads a controller from the internal storyboard.

Parameters:

  • Return Value: controller instance or nil if not successful.

Enumeration UniversalStatus

public enum UniversalStatus : Int

Player status.

ERROR

case ERROR = 0

IDLE

case IDLE

PREPARING

case PREPARING

PLAYING

case PLAYING

PAUSED

case PAUSED

PLAYBACK_COMPLETED

case PLAYBACK_COMPLETED

Enumeration PreviewMp4StatusEnum

public enum PreviewMp4StatusEnum : Int8

Preview status.

noUrl

case noUrl = 0

A preview image is not set yet.

loading

case loading

A preview image is loading.

loaded

case loaded

A preview image was loaded successfully.

loadedFromCache

case loadedFromCache

Undocumented.

error

case error

Error, loading was interrupted.

Protocol FlussonicBufferingListener

public protocol FlussonicBufferingListener

The protocol describes public FlussonicBufferingListener methods.

Used to notify a delegate about buffering events.

onBufferingStart()

func onBufferingStart()

Called when a buffering label appears.

onBufferingStop()

func onBufferingStop()

Called when a buffering label hides.

Protocol FlussonicDownloadRequestListener

public protocol FlussonicDownloadRequestListener : AnyObject

The protocol describes public FlussonicDownloadRequestListener methods.

Used to notify a delegate about download request events.

onDownloadRequest(from: Int64, to: Int64)

func onDownloadRequest(from: Int64, to: Int64)

Called when the user taps the floppy disc button, requesting to download a part of the DVR archive.

Parameters:

  • from: range start in seconds, Unix time
  • to: range end in seconds, Unix time

Important: You will need to implement this handler yourself. To do this:

  1. Generate a URL for downloading of a video fragment by using the streamer address, token, and the start and end time obtained in the handler.

    The URL for downloading is described in the documentation in Export to MP4

    So in our case the URL must comply with the pattern:

    http://{camera.stream_status.server}/{camera.name}/archive-{from}-{duration}.mp4?token={camera.playback_config.token}

    Here:

    • camera - the object that you obtain via one of the API calls: https://flussonic.github.io/watcher-docs/api.html#get--vsaas-api-v2-cameras
      or
      https://flussonic.github.io/watcher-docs/api.html#get--vsaas-api-v2-cameras-(path-name)
    • from - the integer parameter that you obtain in the handler.
    • duration - the duration of the downloaded fragment of video, in seconds. It is the difference of the parameters `to` and `from`. You can adjust this value based on your business logic, for example, by limiting the maximum fragment length.
  2. Download a video fragment by accessing the formed URL.
    This procedure is not part of this SDK because it depends heavily on the technologies, libraries and application logic that you use in your application.
    Therefore, implementation details are left to the choice of the developer integrating this SDK.

Protocol FlussonicPlayerAdapterDelegate

public protocol FlussonicPlayerAdapterDelegate : AnyObject

The protocol describes public FlussonicPlayerAdapter methods.

Used to notify a delegate about changing of the player state.

mediaPlayerStateChanged(_ aNotification: Notification!)

func mediaPlayerStateChanged(_ aNotification: Notification!)

Called when VLCMediaPlayerDelegate mediaPlayerStateChanged happens.

Parameters:

  • aNotification: Notification with the name mediaPlayerStateChanged

See also: FlussonicVlcAdapter.mediaPlayerStateChanged(_: Notification!) (there is a link in ReadMe)

mediaPlayerTimeChanged(_ aNotification: Notification!)

func mediaPlayerTimeChanged(_ aNotification: Notification!)

Called when VLCMediaPlayerDelegate mediaPlayerTimeChanged happens.

Parameters:

  • aNotification: Notification with the name mediaPlayerTimeChanged

See also: FlussonicVlcAdapter.mediaPlayerTimeChanged(_: Notification!) (there is a link in ReadMe)

mediaPlayerTimeChanged(oldTimeValue: Double, newTimeValue: Double)

func mediaPlayerTimeChanged(oldTimeValue: Double, newTimeValue: Double)

Called to change mediaPlayerTime manually.

Parameters:

  • oldTimeValue: Double
  • newTimeValue: Double

See also: FlussonicVlcAdapter.setupTimeObservation() (there is a link in ReadMe)

mediaPlayerSnapshot(_ aNotification: Notification!)

func mediaPlayerSnapshot(_ aNotification: Notification!)

Called for taking a screenshot of video played in a player.

Parameters:

  • aNotification: Notification with the name mediaPlayerSnapshot

See also: FlussonicVlcAdapter.mediaPlayerSnapshot(_: Notification!) (there is a link in ReadMe)

Protocol FlussonicPlayerAdapterProtocol

public protocol FlussonicPlayerAdapterProtocol : AnyObject

The protocol describes public FlussonicPlayerAdapter methods.

Used to implement the adapter for the VLC player required for the Flussonic Watcher SDK for iOS.

delegate

var delegate: FlussonicPlayerAdapterDelegate? { get set }

drawable

var drawable: Any? { get set }

rate

var rate: Float { get set }

videoSize

var videoSize: CGSize { get }

hasVideoOut

var hasVideoOut: Bool { get }

timeValue

var timeValue: Double { get }

mediaUrl

var mediaUrl: URL? { get set }

audioIsMuted

var audioIsMuted: Bool { get set }

lastSnapshot

var lastSnapshot: UIImage? { get }

state

var state: FlussonicPlayerAdapterState { get }

mediaState

var mediaState: FlussonicPlayerAdapterMediaState { get }

play

func play()

pause

func pause()

stop

func stop()

saveVideoSnapshot

func saveVideoSnapshot(at path: String, withWidth width: Int32, andHeight height: Int32)

Protocol FlussonicUpdateProgressEventListener

public protocol FlussonicUpdateProgressEventListener

The protocol describes public FlussonicUpdateProgressEventListener methods.

Used to notify a delegate about update progress events.

onUpdateProgress(event: ProgressEvent)

func onUpdateProgress(event: ProgressEvent)

Called on update progress events.

Protocol FlussonicWatcher

public protocol FlussonicWatcher : AnyObject

The protocol describes public FlussonicWatcherView methods.

Used to notify a delegate about player events.

setAllowDownload(allowDownload: Bool)

func setAllowDownload(allowDownload: Bool)

Sets availability of downloading a portion of video stream as a separate clip.

allowDownload: new setting value.

setStartPosition(dateTimeInSecs: Int64)

func setStartPosition(dateTimeInSecs: Int64)

Sets the starting position for playing video.

An instance of FlussonicWatcherView tries to start playing from this position, if possible.

  • dateTimeInSecs: position to start, Unixtime.

pause()

func pause()

Pauses the current stream.

resume()

func resume()

Resumes the current stream.

Live jumps to live, archive resumes playing from the current point.

seek(seconds: TimeInterval)

public func seek(seconds: TimeInterval)

Tries to play from the specified time.

  • seconds: value to go to, Unixtime

screenshotCaptured: (UIImage) -> ()

public var screenshotCaptured: (UIImage) -> ()

This block is called when a screenshot of a video stream is created.

captureScreenshot(destUrl: URL)

public func captureScreenshot(destUrl: URL)

Creates a screenshot of the currently played stream.

  • destUrl: URL to save image to.

setBufferingListener(bufferingListener: FlussonicBufferingListener?)

public func setBufferingListener(bufferingListener: FlussonicBufferingListener?)

Sets a listener for buffering events.

  • bufferingListener: The instance to be notified.

setDownloadRequestListener(downloadRequestListener: FlussonicDownloadRequestListener?)

public func setDownloadRequestListener(downloadRequestListener: FlussonicDownloadRequestListener?)

Sets a listener for download request events.

  • downloadRequestListener: The instance to be notified.

public func setUpdateProgressEventListener(updateProgressEventListener: FlussonicUpdateProgressEventListener?)

public func setUpdateProgressEventListener(updateProgressEventListener: FlussonicUpdateProgressEventListener?)

Sets a listener for update progress events.

  • updateProgressEventListener: The instance to be notified.

getCurrentUtcInSeconds() -> Int64

public func getCurrentUtcInSeconds() -> Int64

The time (playhead position) at which the player currently plays video.

getPlaybackStatus() -> Int

public func getPlaybackStatus() -> Int

Current playback status.

getSpeed() -> CGFloat

public func getSpeed() -> CGFloat

The speed at which the player plays video.

getAvailableStreams() -> Array<StreamItem>

public func getAvailableStreams() -> Array<StreamItem>

Returns information about tracks in available multi-bitrate streams.

getCurrentStream() -> StreamItem?

public func getCurrentStream() -> StreamItem?

Returns information about tracks in the currently played multi-bitrate stream.

setNetworkQualityThresholdCount(count: Int)

public func setNetworkQualityThresholdCount(count: Int)

The number of interrupts to the player due to a bad network connection after which the player automatically switches to a low bitrate video stream.

  • count: The maximum number of interruptions to the player

setShowDebugInfo(newValue: Bool)

public func setShowDebugInfo(newValue: Bool)

Shows or hides debug info in the right top corner of the player window.

  • newValue: New setting

Protocol FlussonicWatcherDelegateProtocol

public protocol FlussonicWatcherDelegateProtocol : AnyObject

The protocol describes public FlussonicWatcherDelegateProtocol methods.

Used to notify a delegate about toolbar expand/collapse events.

expandToolbar()

func expandToolbar()

Invoked by the player when the bottom toolbar starts to expand.

collapseToolbar()

func collapseToolbar()

Invoked by the player when the bottom toolbar starts to collapse.

showToolbar()

func showToolbar()

Invoked by the player when the bottom toolbar appears without animation.

hideToolbar()

func hideToolbar()

Invoked by the player when the bottom toolbar hides without animation.

Protocol PreviewMp4ViewStatusListener

public protocol PreviewMp4ViewStatusListener : AnyObject

The protocol describes public PreviewMp4ViewStatusListener methods.

Used to notify a delegate about PreviewMp4View status events.

onStatusChanged(_ status: Int8, _ code: String, _ message: String)

func onStatusChanged(_ status: Int8, _ code: String, _ message: String)

This function is invoked when the preview status changes.

  • status: a new status
  • code: error code or 0 if no error
  • message: error message or "" if no error.

Structure CameraItem

The structure describes public CameraItem fields.

Can be used for initialization of FlussonicWatcherView or PreviewMp4View.

public struct CameraItem : Codable

Available globally.

Contains:

  • comment

    public let comment: String?
    
  • playbackConfig

    public let playbackConfig: PlaybackConfigItem
    

    See PlaybackConfigItem

  • name

    public let name: String
    
  • title

    public let title: String
    
  • access

    public let access: String?
    
  • coordinates

    public let coordinates: String?
    
  • streamStatus

    public let streamStatus: StreamStatusItem
    

    See StreamStatusItem

  • isStatic

    public let isStatic: Bool?
    
  • dvrEnabled

    public let dvrEnabled: Bool?
    
  • groups

    public let groups: Array<CameraGroupItem>?
    

    See CameraGroupItem

  • owner

    public let owner: String?
    
  • dvrDepth

    public let dvrDepth: Int64?
    
  • permissions

    public let permissions: [String : Bool?]?
    
  • isAlive

    public func isAlive() -> Bool
    
  • useHttps

    public func useHttps() -> Bool
    
  • currentProtocol

    public func currentProtocol() -> String
    
  • currentPort

    public func currentPort() -> Int32
    

Structure CameraGroupItem

CameraGroupItem is a part of the CameraItem structure.

public struct CameraGroupItem : Codable

Available globally.

Contains:

  • id

    public let id: Int
    
  • title

    public let title: String
    

Structure PlaybackConfigItem

PlaybackConfigItem is a part of the CameraItem structure.

public struct PlaybackConfigItem : Codable

Available globally.

Contains:

  • token

    public let token: String
    

Structure StreamStatusItem

StreamStatusItem is a part of the CameraItem structure.

public struct StreamStatusItem : Codable

Available globally.

Contains:

  • lifetime

    public let lifetime: Int64?
    
  • sourceError

    public let sourceError: String?
    
  • bitrate

    public let bitrate: Int64?
    
  • alive

    public let alive: Bool
    
  • server

    public let server: String
    
  • httpPort

    public let httpPort: Int32?
    
  • httpsPort

    public let httpsPort: Int32?
    

Structure StreamItem

StreamItem describes the selected stream.

public struct StreamItem : Codable

Available globally.

Contains:

  • bitrate

    public let bitrate: UInt32
    
  • codec

    public let codec: String
    
  • content

    public let content: StreamItemContentTyp
    
  • height

    public let height: Double?
    
  • lang

    public let lang: String?
    
  • lengthSize

    public let lengthSize: UInt32?
    
  • level

    public let level: String?
    
  • pixelHeight

    public let pixelHeight: Double?
    
  • pixelWidth

    public let pixelWidth: Double?
    
  • profile

    public let profile: String?
    
  • sarHeight

    public let sarHeight: Double?
    
  • sarWidth

    public let sarWidth: Double?
    
  • size

    public let size: String?
    
  • trackId

    public let trackId: String
    
  • width

    public let width: Double?