Skip to main content

API

Reference​

initialize​

Initializes the sdk. Widgets can be created after successfull initialization.

initialize (
  InitializationConfig, 
  Callback<InitializeResult>
)
InitializationConfig​
InitializationConfig {
  token: string,
}
Key
Description
token
A Video SDK Token is required for SDK authentication. Reach out to Hippo Video Support (support@hippovideo.io) for Video SDK Token

InitializeResult​
InitializeResult (
  successData: {
    key: string,
  },
  errorData: {
    error: string,
    message: string
  }
)
info

successData will be undefined if there is an error. Similarly errorData will be undefined is initialize is successfull

Key
Description
key
The sdk instance key which is required for creating the Record, Import or Edit Widgets
error
Contains a short error message
message
Contains detailed error message

Recorder​

create​

create(
  initializeKey,
  RecordWidgetConfig,
  WidgetErrorCallback 
) => Promise::Success<RecorderInstance> or Promise::Error<CreateError>
info

The resolved RecorderInstance is used to access the Recorder methods

danger

In case there is an error while creating the Widget, the Promise is 'rejected' to return CreateError

Key
Description
initializeKey
The key from success callback in initialize method
RecordWidgetConfig
RecordWidgetConfig
WidgetErrorCallback
WidgetErrorCallback

WidgetErrorCallback​
WidgetErrorCallback () => {
  error: string,
  message: string,
  class_name: string
}

errors/#widget-create-errors

Key
Description
error
Contains a short error message
message
Contains detailed error message
class_name
Contains class name of the widget for which this error occured
info

More details can be found at WidgetErrorCallback Errors


caution

RecorderInstance required to access the below APIs

on​

Creates a listener for the Recorder events.

on(
  event_name: string,
  callback: Callback<EventData>
)
info

Please refer to Events and Data section for more details on the different events for Recorder

open​

Opens the created Record Widget.

open()

startRecording​

Initiates the recording.

startRecording(
  config: RecordingConfig
)
Key
Description
config
RecordingConfig. This is optional if its already passed in create

stopRecording​

Stops the recording.

stopRecording()

pauseRecording​

Pauses the recording already in progress.

pauseRecording()

resumeRecording​

Resumes the recording which was paused.

resumeRecording()

cancelRecording​

Cancels the recording in progress.

cancelRecording()

Importer​

create​

create(
  initializeKey,
  ImportWidgetConfig,
  WidgetErrorCallback
) => Promise::Success<ImporterInstance> or Promise::Error<CreateError>
info

The resolved ImporterInstance is used to access the Importer APIs

danger

In case there is an error while creating the Widget, the Promise is 'rejected' to return CreateError

Key
Description
initializeKey
The key from success callback in initialize method
ImportWidgetConfig
ImportWidgetConfig
WidgetErrorCallback
WidgetErrorCallback

caution

ImporterInstance required to access the below APIs

on​

Creates a listener for the Importer events.

on(
  event_name: string,
  callback: Callback<EventData>
)
info

Please refer to Events and Data section for more details on the different events for Importer

open​

Opens the Import Widget.

open()

importMedia​

Uploads video/audio file.

importMedia(
  file: File
)
Key
Description
file
File object to upload. (Optional) If file object is not passed, file picker dialog box opens to select video/audio file

Editor​

create​

create(
  initializeKey,
  EditWidgetConfig,
  WidgetErrorCallback
) => Promise::Success<EditorInstance> or Promise::Error<CreateError>
info

The resolved EditorInstance is used to access the Editor methods

danger

In case there is an error while creating the Widget, the Promise is 'rejected' to return CreateError

Key
Description
initializeKey
The key from success callback in initialize method
EditWidgetConfig
EditWidgetConfig
WidgetErrorCallback
WidgetErrorCallback

caution

EditorInstance required to access the below APIs

on​

Creates a listener for the Editor events.

on(
  event_name: string,
  callback: Callback<EventData>
)
info

Please refer to Events and Data section for more details on the different events for Editor

open​

Opens the Edit Widget.

open()

Additional Types​

RecordWidgetConfig​

RecordWidgetConfig {
  record_config: RecordingConfig
  inline: boolean (or) InlineConfig,
  video_title: boolean (or) VideoTitleConfig,
  retake_video: boolean,
  edit: boolean (or) EditConfig,
  show_mirror_webcam: boolean,
  virtual_background:boolean,
  custom_thumbnail:boolean (or) CustomThumbnailConfig,
  advanced_settings: AdvancedSettingsConfig
}
Key
Description
record_config
RecordingConfig
inline
InlineConfig.
video_title
Show an editable video title after the recording is completed. Can be customized with VideoTitleConfig
retake_video
Show an option to retake recording after the recording is completed. Cancels the current recording before starting a new one.
edit
Show edit option after the recording is completed. false will not show the edit option.
By default all edit options will be shown which can be further customized with EditConfig
show_mirror_webcam
Enable the mirror webcam option in record preview screen to mirror the webcam
Defaults to false
virtual_background
Enable/disable virtual background option.
Defaults to false
custom_thumbnail
Enable/disable thumbnail customization. Can be customized with CustomThumbnailConfig
Defaults to false
advanced_settings
AdvancedSettingsConfig

RecordingConfig​

RecordingConfig {
  teleprompter: boolean (or) TeleprompterConfig,
  show_selectable_options: boolean,
  screen: boolean,
  webcam: boolean,
  mic: boolean,
  resolution: string,
  enable_markup_tool: boolean,
  mirror_webcam: boolean,
  max_recording_time: number
}
Key
Description
teleprompter
Enable/disable teleprompter for webcam/mic recording.
TeleprompterConfig - Configuration for teleprompter can also be passed
Teleprompter is not available for screen recording.
Defaults to false
show_selectable_options
Enable/disable user to select the recording options (screen/webcam/mic) in the recording preview screen.
Defaults to true
screen
Enable/disable 'Screen' option in the recording preview screen
Defaults to true
webcam
Enable/disable 'Webcam' option in the recording preview screen
Defaults to true
mic
Enable/disable 'Mic' option in the recording preview screen
Defaults to true
resolution
Resolution for screen recording.
Possible values are "1080", "720", "480" or "360".
Defaults to "1080"
enable_markup_tool
Enable/disable markup tools during screen recording.
Defaults to true
mirror_webcam
Mirrors the webcam
Defaults to false
max_recording_time
Maximum allowed recording time in seconds

ImportWidgetConfig​

ImportWidgetConfig {
  inline: boolean (or) InlineConfig,
  video_title: boolean (or) VideoTitleConfig,
  edit: boolean (or) EditConfig,
}

Key
Description
inline
InlineConfig
video_title
Show an editable video title after the import is completed. Can be customized with VideoTitleConfig
edit
Show edit option after the recording is completed. false will not show the edit option.
By default all edit options will be shown which can be further customized with EditConfig

EditWidgetConfig​

EditWidgetConfig {
  editor_config: EditorConfig,
  inline: boolean (or) InlineConfig,
  video_title: boolean (or) VideoTitleConfig,
  edit: boolean (or) EditConfig,
}

Key
Description
editor_config
EditorConfig
inline
InlineConfig
video_title
Show an editable video title after the editing is completed. Can be customized with VideoTitleConfig
edit
Show edit option after the recording is completed. false will not show the edit option.
By default all edit options will be shown which can be further customized with EditConfig

EditorConfig​

EditorConfig {
  asset_id: number
}

Key
Description
asset_id
The asset id of the video or audio. This will be available via the Widget Events.
This will be present in the record_details event for recording and import_complete event for import.

InlineConfig​

Opens the widget inside the given HTML element than opening it in a modal.

InlineConfig {
  open: boolean,
  element: ElementDOM,
  element_id: ElementDOM_ID
}
Key
Description
open
Open the widget upon creation. Defaults to true
element
Provide the ElementDOM where the widget needs to be loaded.
Not required if element_id is provided
element_id
Provide the ElementDOM_ID where the widget needs to be loaded.
Not required if element is provided

VideoTitleConfig​

VideoTitleConfig {
  title: string,
  editable: boolean,
}
Key
Description
title
A custom title for the recording or import.
editable
Whether the title can be editable after finishing recording or import. Defaults to true.

TeleprompterConfig​

TeleprompterConfig {
  script_id: number,
  script: string,
  change_script: boolean,
  text_size: number,
  line_space: number,
  speed: number
}
Key
Description
script_id
The id of the teleprompter script in Hippo Video. Defaults to 0
script
A custom script to be loaded into the teleprompter. If provided script_id is ignored.
change_script
Provide user with option to change the current script.
Defaults to false
text_size
The text size of script inside teleprompter in px. Defaults to 15
Minimum text size 15. Maximum text size 45
line_space
The line space between the script. Defaults to 1
The value can be a float, example 1.25
Minimum line space 1. Maximum line space 3
speed
The scroll speed of the teleprompter script. Defaults to 2
Minimum speed 1. Maximum speed 10

EditConfig​

EditConfig {
  trim: boolean, 
  crop: boolean, 
  text: boolean, 
  stickers: boolean, 
  callout: boolean, 
  blur: boolean, 
  image: boolean, 
  resize: boolean
}
Key
Description
trim
Show/hide option to trim the recording.
Defaults to true
crop
Show/hide option to crop the recording.
Defaults to true
text
Show/hide option to add text to the recording.
Defaults to true
stickers
Show/hide option to add stickers to the recording.
Defaults to true
callout
Show/hide option to add callouts to the recording.
Defaults to true
blur
Show/hide option to blur parts of the recording.
Defaults to true
image
Show/hide option to add images to the recording.
Defaults to true
resize
Show/hide option to resize the dimensions of the recording.
Defaults to true

AdvancedSettingsConfig​

AdvancedSettingsConfig {
  show_system_audio: boolean,
  show_markup_tools: boolean,
  show_lower_third: boolean,
  show_center_webcam: boolean,
  show_webcam_source: boolean,
  show_audio_source: boolean,
  show_aspect_ratio: boolean,
  show_webcam_shape: boolean,
  show_webcam_size: boolean,
  show_webcam_position: boolean,
  show_video_resolution: boolean,
}
Key
Description
show_system_audio
Show/hide option to capture system audio.
Available only for Screen recording
System audio is only availble for 'Tab recording' in MacOS
Defaults to true
show_markup_tools
Show/hide option to enable markup tools.
Available only for Screen recording
Defaults to true
show_lower_third
Show/hide option to enable lower third.
Available only for Screen recording with circle webcam shape
Defaults to true
show_center_webcam
Show/hide option to enable center webcam.
Available only for Screen recording
Defaults to true
show_webcam_source
Show/hide option to enable webcam source selection.
Defaults to true
show_audio_source
Show/hide option to enable mic source selection.
Defaults to true
show_aspect_ratio
Show/hide option to set aspect ratio.
show_webcam_shape
Show/hide option to set the shape of floating webcam preview.
Available only for Screen recording
show_webcam_size
Show/hide option to set the size of floating webcam preview.
Available only for Screen recording
show_webcam_position
Show/hide option to set the position of floating webcam preview.
Available only for Screen recording
show_video_resolution
Show/hide option to set resolution for the the screen recording.
Available only for Screen recording

CustomThumbnailConfig​

CustomThumbnailConfig {
  default_frame: boolean,
  gif_preview: boolean,
  upload_new_frame: boolean,
  select_frame: boolean,
  customize_thumbnail: boolean
}
Key
Description
default_frame
Enable or disable option for selecting default frame as thumbnail.
Defaults to true
gif_preview
Enable or disable option for selecting gif as thumbnail.
Defaults to true
upload_new_frame
Enable or disable option to upload new frame as thumbnail.
Defaults to true
select_frame
Enable or disable option to select a particular frame from video as thumbnail.
Defaults to true
customize_thumbnail
Enable or disable option to customize existing thumbnail.
Defaults to true

Events And Data​

The following events are available which can be listened to with the on API of respective Widgets.

Event
Description
Event Data
sdk_loaded
The widget loading is completed
-
countdown_timer
Countdown time before the recording starts
time_left (number) - countdown time left
countdown_complete
Countdown is completed
-
record_started
The recording has started
-
recording_timer
The current recording time in seconds
time (number) - current recording time in seconds
record_details
fired when the recording is created
asset_id: Asset ID of the recording

token: Video token for the recorded video.

play_url: Video delivery URL. URL to share/mail/message others.

embed_url: Similar to play_url. Optimized for embedding as an iframe in a website.

embed_preview_url: URL to preview video. (preview will be available at any point of time for the recorded user. For others, it will be the same as 'play_url')

thumbnail_url: Thumbnail URL of the video.

thumbnail_play_url: Similar to 'thumbnail_url', except the play icon is displayed at the center.

record_paused
fired when the recording paused
Nil
record_resumed
fired when the recording resumed
Nil
record_stopped
fired when the recording stopped
Nil
record_aborted
fired when the recording aborted
Nil
record_error
fired when error occurred while recording
message: Contains the error sub-type.

error: Detailed message for the error.
source_uploaded
fired when the source uploaded
Nil
video_cancelled
fired when the video cancelled
Nil
video_submitted
fired when the video submitted
Same as record_details
video_title_updated
fired when the video title is updated
title: Updated video title