Watcher API for iOS Apps
This page contains the description of Mobile Watcher API for iOS.
Classes
Enumerations
Protocols
- FlussonicBufferingListener
- FlussonicDownloadRequestListener
- FlussonicPlayerAdapterDelegate
- FlussonicPlayerAdapterProtocol
- FlussonicUpdateProgressEventListener
- FlussonicWatcher
- FlussonicWatcherDelegateProtocol
- PreviewMp4ViewStatusListener
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:
- url: URL — an URL like http[s]://access_token@host.com/camera_name[?from=1545660274]
- adapter: FlussonicPlayerAdapterProtocol — an instance of the
FlussonicVlcAdapter
class or another implementation of FlussonicPlayerAdapterProtocol.
(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:
- cameraItem: CameraItem
- adapter: FlussonicPlayerAdapterProtocol — an instance of the
FlussonicVlcAdapter
class or another implementation of FlussonicPlayerAdapterProtocol.
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:
- cameraItem: CameraItem
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.
setCacheKey(to cacheKey: String?)
public func setCacheKey(to cacheKey: String?)
Clears the cache of URL previews and reloads previews with new cacheKey.
A preview download currently in progress will not be canceled, and the preview image will be cached on successful download.
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:
-
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-camerasor
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 parametersto
andfrom
. You can adjust this value based on your business logic, for example, by limiting the maximum fragment length.
-
-
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?