Watcher API for Android Apps

Here is a description of the main API of the components FlussonicWatcherView andFlussonicThumbnailView.

For more information, see the description of the API in javadoc comments and in the javadoc documentation (to be published later).

FlussonicWatcherView

void setAllowDownload(boolean allowDownload);

Displays or hides the scissors icon. When the user clicks the scissors, the player opens the mode for interval selection. The user chooses the start time point and the end time point of the interval to be downloaded. You can set this property also in XML markup.

void setStartPosition(long dateTimeInSecs);

Sets the start point for video playback that takes place when opening the component FlussonicWatcherView. You can set this property also in XML markup.

void pause();

Pauses the player.

void resume();

Resumes playback.

void seek(long seconds);

Jumps to the selected time poinp (this is used, for example, when the user chooses a time point in the Calendar.

Completable captureScreenshot(@NonNull Uri uri);

Creates a screenshot of the current video frame, and saves the resulting file to the specified URI address (an URI is used on Android as a general way to specify where to save a file, allowing saving files to an SD card or, for example, passing the file to an external app).

An open method from the React Native SDK that perfroms the same action, has a different signature: it takes the fileName parameter (a PNG file name) on input and (optionally) the directory name picturesSubdirectoryName. On the device, a subfolder is created in the Gallery (on Android, it's usually Pictures on a SD card), and the screenshot file is saved to that subfolder. The subfolder name and the file name are passed to the method in the respective parameters.

void setBufferingListener(@Nullable FlussonicBufferingListener bufferingListener);

Sets a listener for buffering events.

FlussonicBufferingListener — an interface containing two methods:

void onBufferingStart();

void onBufferingStop();

void setDownloadRequestListener(@Nullable FlussonicDownloadRequestListener downloadRequestListener);

Sets a listener for events of clicking on the Save icon. The user selects an interval of a DVR archive in interval selection mode and clicks Save.

FlussonicDownloadRequestListener — an interface containing a method:

void onDownloadRequest(long from, long to);

Here the parameters from and to — are boundaries of the interval selected for downloading (in seconds).

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-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.
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.

void setUpdateProgressEventListener(@Nullable FlussonicUpdateProgressEventListener updateProgressEventListener);

Sets a listener for player state updating event called every 500 milliseconds.

FlussonicUpdateProgressEventListener — an interface containing a single method:

void onUpdateProgress(@NonNull UpdateProgressEvent event);

The object UpdateProgressEvent has methods:

long currentUtcInSeconds() (current playing time)
PlaybackStatus playbackStatus() (playing status)
float speed() (playing speed).

These methods corresponds to getters in FlussonicWatcherView. The values must be packed into an object for being able to pass them to the React Native version of the Flussonic Watcher SDK.

long getCurrentUtcInSeconds();

The current playing time in UTC, in seconds.

PlaybackStatus getPlaybackStatus();

The current playing status. Values: ERROR, IDLE, PREPARING, PLAYING, PAUSED, PLAYBACK_COMPLETED. In Java, PlaybackStatus is an enum. In React Native it must be passed as a string containing respective values.

float getSpeed();

The current playing speed. Values: 0.5х, 1х, 2х, 4х, 8х, 16х.

void setExoPlayerErrorListener(@Nullable FlussonicExoPlayerErrorListener exoPlayerErrorListener);

Sets a listener for player error events that can occur when playing video.

You can use this method for debugging, testing, and researching frame download and display issues.

FlussonicExoPlayerErrorListener — an interface containing a single method:

void onExoPlayerError(String code, String message, String url);

Here:

code contains an error code (in the current SDK version, it is always PLAYBACK_ERROR_HARDWARE)
message — the error message
url — the URL of the camera. This URL was passed to the method FlussonicWatcherView#setUrl.

void setCollapseExpandTimelineListener(@Nullable FlussonicCollapseExpandTimelineListener collapseExpandTimelineListener);

Sets a listener for events of hiding or showing the toolbar (with the usage of animation or without it).

FlussonicCollapseExpandTimelineListener is an interface containing methods:

void collapseToolbar(int animationDuration); — hides the toolbar applying animation, animationDuration — animation duration, in milliseconds, >0.
void expandToolbar(int animationDuration); — shows the toolbar applying animation, animationDuration — animation duration, in milliseconds, >0.
void showToolbar(int animationDuration); — shows the toolbar without applying animation, animationDuration — animation duration, in milliseconds, >0

(in code for Android you can show a toolbar without animation but in JS code anumation is used, this is why we use animationDuration).
void hideToolbar(int animationDuration); — shows the toolbar without applying animation, animationDuration — animation duration, in milliseconds, >0

(in code for Android you can hide a toolbar without animation but in JS code anumation is used, this is why we use animationDuration).

For details, see the javadoc documentation and the example of a toolbar animation in the demo app.

void setToolbarHeight(int toolbarHeight);

A method for setting the toolbar height, if you use a toolbar in your app. It is necessary for the correct rendering of the position of the Pause/Resume button when animating the toolbar.

For details, see the javadoc documentation and the example of a toolbar animation in the demo app.

int getAnimationDuration()

Returns the duration of animation when expanding or collapsing the timeline. This method can be used for creating animations that take place in sync with the timeline animation. For example, for animation of the toolbar in the window containing FlussonicWatcherView).

For details, see the javadoc documentation and the example of a toolbar animation in the demo app.

List<Track> getAvailableTracks();

Returns tracks available for playback.

When playing the DVR archive, the object Track is initialized only in part: trackId, bitrate, codec, height, width, size, and profile.

Other fields are initialized with zeros and empty strings.

@Nullable Track getCurrentTrack();

A track that is currently being played. When playing the DVR archive, the Track object is initialized only partially (see List<Track>getAvailableTracks above).

void release

"Cleans up" FlussonicWatcherView: resets links, stops and clears the player, stops timers, cancels subscriptions, etc.

The method is designed to be used if you need to remove FlussonicWatcherView dynamically. This method is used in the React Native module of the Flussonic Watcher SDK.

void clearCache()

Removes from memory the data required to draw ranges on the timeline. The data will then be reloaded as needed. This method is to be used in the Activity#onLowMemory()callback.

void initialize(@NonNull FragmentActivity activity)

See FlussonicWatcherView initializing.

void initialize(@NonNull FragmentActivity activity, boolean reactNative)

See FlussonicWatcherView initializing.

void initialize(@NonNull Fragment fragment)

See FlussonicWatcherView initializing.

void setUrl(@NonNull String url)

See FlussonicWatcherView initializing.

FlussonicThumbnailView

void setUrl(@NonNull String url)

See FlussonicThumbnailView initializing.

void show(@NonNull Camera camera, @Nullable Date date)

See FlussonicThumbnailView initializing.

void cancelRequest()

Cancels a request for a frame downloading. This method must be used for dynamic deletion of FlussonicThumbnailView. It is found in the React Native module of the Flussonic Watcher SDK.

void setStatusListener(@Nullable StatusListener statusListener)

Sets the listener for the event of the status of frame downloading change. You can use this method for debugging, testing, and researching frame download and display issues.

StatusListener — an interface containing a single method:

void onStatus(Status status, String code, String message);

The status can have the following values: LOADING, LOADED, ERROR;
The parameter code contains an error code. The supported values are: an HTTP status code or PLAYBACK_ERROR_HARDWARE if the device fails to display the frame. This parameter must be an empty string if there are no errors;
The parameter message contains an error message or the text 'loading' or 'loaded' if there are no errors.

void setCacheKey(@NonNull String cacheKey)

Refreshes the cache of screenshots (thumbnails). If the cached value differs from the value of the cacheKey parameter, then a new screenshot will be loaded. You can implement thumbnails auto update in your app by calling this method from time to time.

The cacheKey is an optional parameter:

If cacheKey is not specified, then the current screenshot URL is used for caching; when the URL changes, a new screenshot is loaded. This way of calling the method can be used if the screenshot URL explicitly specifies a time that is constantly changing.
When cacheKey is specified, a new screenshot is loaded when the cacheKey OR URL changes. This way of calling the method is applicable for live stream screenshot when URL does not change.

Please refer to Taking video screenshots from the Watcher camera for details on making URLs for thumbnails.