Описание API Flussonic Watcher SDK

Здесь представлено описание основного API компонентов FlussonicWatcherView и FlussonicThumbnailView.

Для дополнительной информации смотрите описание API в javadoc-комментариях и в javadoc-документации (будет опубликована позднее).

FlussonicWatcherView

void setAllowDownload(boolean allowDownload);

Отображать или скрывать иконку ножниц. При нажатии на ножницы происходит переход к режиму выбора отрезка, в котором пользователь выбирает две временные точки, видео между которыми он хотел бы загрузить.

Это свойство можно также задавать в XML-разметке.

void setStartPosition(long dateTimeInSecs);

Задание стартовой позиции, откуда надо начать проигрывание при открытии компонента FlussonicWatcherView.

Это свойство можно также задавать в XML-разметке.

void pause();

Поставить плеер на паузу.

void resume();

Возобновить проигрывание.

void seek(long seconds);

Перейти к заданному времени (используется, например, при выборе времени через календарь).

Completable captureScreenshot(@NonNull Uri uri);

Сделать скриншот текущей картинки, отображаемой на плеере и сохранить полученное изображение по адресу URI (URI используется в Android как более общий способ задания места сохранения файла, можно сохранять файл как на SD карту, так и, например, передавать его другому приложению).

Открытый метод из React Native SDK, выполняющий соответствующую функцию, имеет другую сигнатуру: он принимает на вход параметр fileName (имя PNG файла) и (опционально) имя директории picturesSubdirectoryName. При этом в галерее устройства (для Android — это обычно директория Pictures на SD карте) создается поддиректория с именем, переданными в соответствующем параметре, и файл с изображением сохраняется в эту поддиректорию с именем, переданным в соответствующем параметре.

void setBufferingListener(@Nullable FlussonicBufferingListener bufferingListener);

Установка слушателя событий буферизации.

FlussonicBufferingListener — интерфейс с двумя методами:

void onBufferingStart();

void onBufferingStop();

void setDownloadRequestListener(@Nullable FlussonicDownloadRequestListener downloadRequestListener);

Установка слушателя события нажатия на иконку с дискетой для сохранения выбранного куска архива в режиме выбора отрезка.

FlussonicDownloadRequestListener — интерфейс, имеющий метод:

void onDownloadRequest(long from, long to);

Параметры from и to — это концы отрезка видео (в секундах), выбранного пользователем для загрузки.

Внимание! Этот обработчик вамнеобходимо реализовать самостоятельно. Для этого нужно:

Сформировать URL для скачивания, используя адрес стримера, токен и полученное в обработчике время начала и конца.

URL на скачивание формируется согласно документации Экспорт в MP4.

URL должен иметь следующий вид: http://{camera.stream_status.server}/{camera.name}/archive-{from}-{duration}.mp4?token={camera.playback_config.token}

где:
- camera — объект, полученный из API https://flussonic.github.io/watcher-docs/api.html#get--vsaas-api-v2-cameras
  
  или
  
  https://flussonic.github.io/watcher-docs/api.html#get--vsaas-api-v2-cameras-(path-name)
- from — целочисленный параметр, полученный в обработчике.
- duration — длительность выгружаемого видеофрагмента в секундах. Формируется как разность параметров to, from. Вы можете корректировать это значение на основе вашей бизнес-логики, например, ограничивая максимальную длительность фрагмента.
Произвести загрузку видеофрагмента, обратившись по полученному URL.

Эта процедура не является частью данного SDK, так как сильно зависит от используемых в приложении технологий, библиотек и прикладной логики. Поэтому детали реализации оставляются на выбор разработчику, интегрирующему данный SDK.

void setUpdateProgressEventListener(@Nullable FlussonicUpdateProgressEventListener updateProgressEventListener);

Установка слушателя на событие обновления состояния плеера, вызывается каждые 500 миллисекунд.

FlussonicUpdateProgressEventListener` — интерфейс с одним методом:

void onUpdateProgress(@NonNull UpdateProgressEvent event);

объект UpdateProgressEvent имеет методы:

long currentUtcInSeconds() (текущее время проигрывания)
PlaybackStatus playbackStatus() (статус проигрывания)
float speed() (скорость проигрывания).

Эти методы соответствуют соответствующим геттерам FlussonicWatcherView. Эти значения запаковываются в объект в связи с необходимостью передачи их в React Native версию Flussonic Watcher SDK.

long getCurrentUtcInSeconds();

Текущее время проигрывания UTC, в секундах.

PlaybackStatus getPlaybackStatus();

Текущий статус проигрывания, возможные значения: ERROR, IDLE, PREPARING, PLAYING, PAUSED, PLAYBACK_COMPLETED. В Java PlaybackStatus представляет собой enum, в React Native передается в виде строки с соответствующими значениями.

float getSpeed();

Текущая скорость проигрывания, возможные значения: 0.5х, 1х, 2х, 4х, 8х, 16х.

void setExoPlayerErrorListener(@Nullable FlussonicExoPlayerErrorListener exoPlayerErrorListener);

Установка слушателя на событие возникновения какой-либо ошибки в плеере при проигрывании видео. Этот метод можно использовать для отладки, тестирования и поиска проблем при проигрывании видео с какой-либо камеры.

FlussonicExoPlayerErrorListener — интерфейс с одним методом:

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

Где:

code будет содержать код ошибки (в настоящее время всегда PLAYBACK_ERROR_HARDWARE)
message — сообщение об ошибке
url — URL камеры, который был передан в метод FlussonicWatcherView#setUrl.

void setCollapseExpandTimelineListener(@Nullable FlussonicCollapseExpandTimelineListener collapseExpandTimelineListener);

Установка слушателя событий, когда следует показать или скрыть тулбар с анимацией или без анимации.

FlussonicCollapseExpandTimelineListener — интерфейс с методами:

void collapseToolbar(int animationDuration); — скрыть тулбар с анимацией, animationDuration — продолжительность анимации, в миллисекундах, >0.
void expandToolbar(int animationDuration); — показать тулбар с анимацией, animationDuration — продолжительность анимации, в миллисекундах, >0.
void showToolbar(int animationDuration); — показать тулбар без анимации, animationDuration — продолжительность анимации, в миллисекундах, >0

(в Android-коде можно показать тулбар без анимации, в JS-коде тулбар отображается с анимацией, поэтому используется продолжительность анимации).
void hideToolbar(int animationDuration); — скрыть тулбар без анимации, animationDuration — продолжительность анимации, в миллисекундах, >0.

(в Android-коде можно скрыть тулбар без анимации, в JS-коде тулбар скрывается с анимацией, поэтому используется продолжительность анимации).

Для более полной информации см. javadoc-документацию и пример анимации тулбара в демо-приложении.

void setToolbarHeight(int toolbarHeight);

Метод для установки высоты тулбара, если в приложении-клиенте есть тулбар. Необходим для правильной отрисовки положения кнопки Pause/Resume при анимации тулбара.

Для более полной информации см. javadoc-документацию и пример анимации тулбара в демо-приложении.

int getAnimationDuration()

Возвращает продолжительность анимации сворачивания/разворачивания таймлайна. Этот метод можно использовать для организации анимаций, синхронных с анимацией таймлайна (например, анимацию тулбара окна, в котором расположено FlussonicWatcherView).

Для более полной информации см. javadoc-документацию и пример анимации тулбара в демо-приложении.

List<Track> getAvailableTracks();

Доступные дорожки для воспроизведения. При проигрывании архива, объект Track заполняется только частично: trackId, bitrate, codec, height, width, size, profile.
Остальные поля инициализированы нулями и пустыми строками.

@Nullable Track getCurrentTrack();

Текущая проигрываемая дорожка. При проигрывании архива объект Track заполнен только частично (см. List<Track> getAvailableTracks).

void release

Осуществляет "очистку" FlussonicWatcherView: обнуляет ссылки, останавливает и очищает плеер, останавливает таймеры, отменяет подписки и т.п.

Метод предназначен для использования в случае, если необходимо удалить FlussonicWatcherView динамически. Метод используется в React Native модуле Flussonic Watcher SDK.

void clearCache()

Удаляет из памяти данные, необходимые для отрисовки диапазонов на таймлайне. После этого данные будут подгружены заново по мере необходимости. Предполагается использовать этот метод в обратном вызове Activity#onLowMemory().

void initialize(@NonNull FragmentActivity activity)

См. раздел об инициализации FlussonicWatcherView.

void initialize(@NonNull FragmentActivity activity, boolean reactNative)

См. раздел об инициализации FlussonicWatcherView.

void initialize(@NonNull Fragment fragment)

См. раздел об инициализации FlussonicWatcherView.

void setUrl(@NonNull String url)

См. раздел об инициализации FlussonicWatcherView.

FlussonicThumbnailView

void setUrl(@NonNull String url)

См. раздел об инициализации FlussonicThumbnailView.

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

См. раздел об инициализации FlussonicThumbnailView.

void cancelRequest()

Отменяет запрос на загрузку кадра. Этот метод необходимо использовать при динамическом удалении FlussonicThumbnailView. Этот метод используется в React Native модуле Flussonic Watcher SDK.

void setStatusListener(@Nullable StatusListener statusListener)

Установка слушателя на события изменения статуса загрузки кадра. Этот метод можно использовать для отладки, тестирования и поиска проблем, возникающих при загрузке или отображении кадра.

StatusListener — интерфейс с одним методом:

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

возможные значения status: LOADING, LOADED, ERROR;
параметр code будет содержать код ошибки (возможные значения: код состояния HTTP или PLAYBACK_ERROR_HARDWARE в случае проблем отображения кадра на устройстве) или пустую строку, если ошибок нет;
параметр message — сообщение об ошибке или строки loading или loaded, если ошибок нет.

void setCacheKey(@NonNull String cacheKey)

Обновляет кэш скриншотов (thumbnails). Если в момент вызова метода значение в кэше отличается от значения параметра cacheKey, то будет загружен новый скриншот. Периодически вызывая этот метод, вы можете реализовать автообновление скриншотов в своем приложении.

Параметр cacheKey указывать не обязательно:

Если cacheKey не указан, то для кэширования используется текущий URL скриншота, и при смене URL загружается новый скриншот. Такой способ вызова метода можно использовать, если в URL скриншота явно указывается время, которое постоянно меняется.
Когда cacheKey указан, новый скриншот загружается при смене cacheKey или URL. Этот способ вызова метода подходит, если используются скриншоты живого потока, когда URL-адрес не меняется.

О формировании URL видео-скриншотов см. в разделе Снятие видео-скриншотов c камеры Watcher.