Class: MediaPlayer

Constructor

new MediaPlayer(ffmpeg_pathopt)

Initializes the MediaPlayer UI component.

Parameters:

Name	Type	Attributes	Default	Description
`ffmpeg_path`	string	<optional>	null	Optional path to FFMPEG executable. If omitted, the command "ffmpeg" will be used to run it. In that case the "ffmpeg" path should be added to system's PATH list.

Classes

MediaPlayer

Members

(readonly) Interpolation :number

Enum for video interpolation methods. Used to smooth resized video and reduce pixelation.

Type:

number

Properties

Name	Type	Description
`None`	number	No interpolation applied.
`ByGUI`	number	Interpolation performed by the GUI.
`ByFFMPEG`	number	Interpolation performed by FFMPEG.

Example

player.interpolation(MediaPlayer.Interpolation.ByFFMPEG);

(readonly) State :number

Enum for media player states.

Type:

number

Properties

Name	Type	Description
`NoMedia`	number	No media loaded.
`Stopped`	number	Media is stopped.
`Playing`	number	Media is playing.

See: MediaPlayer#state

Example

if(player.state === MediaPlayer.State.Playing)
{
    console.log("Player is playing");
}

(readonly) hardwareAccelerations :Array.<string>

Gets a list of supported hardware acceleration options that can be used by FFMPEG on this system. Returns an array of supported hardware accelerations that cab be used to decode a video by FFMPEG.

Type:

Array.<string>

(readonly) inputAudioDevices :Array.<object>

Gets an array of enabled audio input devices (such as microphone, system sound) with an array of accepted audio formats (sample rate, bit depth, and amount of channels). Returns an array of objects that contain information about each audio input device recognized by FFMPEG.

Type:

Array.<object>

(readonly) inputVideoDevices :Array.<object>

Gets an array of enabled video input devices (such as WebCam or video capture device) with an array of accepted video formats (size and frame rate). Returns an array of objects that contain information about each video input device recognized by FFMPEG.

Type:

Array.<object>

(readonly) outputAudioDevices :Array.<object>

Gets a list of output audio devices (such as speaker, bluetooth headphones, etc.) and their accepted audio formats. These devices may be specified to be used while playing video or audio. Returns an array of objects that contain information about each audio output device recognized by FFMPEG.

Type:

Array.<object>

(readonly) state :MediaPlayer.State

Gets the current state of the media player component. The returned value corresponds to MediaPlayer#State.

Type:

MediaPlayer.State

See: MediaPlayer#State

Methods

fit(fitopt) → {boolean|MediaPlayer}

Sets or get whether video frame should be resized to fit the media player component.

Parameters:

Name	Type	Attributes	Description
`fit`	boolean	<optional>	`true` to resize video to fit player component, `false` to use actual resolution of the video.

Returns:

Returns this component instance if setting, boolean if getting.

Type:: boolean | MediaPlayer

hardwareAcceleration(hwaccelopt) → {string|MediaPlayer}

Sets or get hardware acceleration setting for ffmpeg video decoding. To get a list of supported hardware acceleration options use hardwareAccelerations getter property.

Parameters:

Name	Type	Attributes	Description
`hwaccel`	string	<optional>	`-hwaccel` option value for FFMPEG. Default is "auto". `null` or "none" to disable hardware acceleration.

Returns:

Returns this component instance if setting, string if getting.

Type:: string | MediaPlayer

interpolation(interpolationopt) → {MediaPlayer.Interpolation|MediaPlayer}

Sets or gets the method how smoothing is done when video is resized. ByGUI means that video frames are smoothed out while drawing on the player component in GUI. ByFFMPEG means that ffmpeg will resize video to the size of the component before sending it to GUI. When component is resized while video is playing, the video will have to stop and then start again at the same position. None means that video will not be smoothed, and when it's resized, it will look pixelated.

Parameters:

Name	Type	Attributes	Description
`interpolation`	MediaPlayer.Interpolation	<optional>	Specifies a method of smoothing video when it's displayed in not it's original size. Options: MediaPlayer.Interpolation.[None\|ByGUI\|ByFFMPEG]

Returns:

When setting value an instance of this object is returned, otherwise a current value is returned.

Type:: MediaPlayer.Interpolation | MediaPlayer

loop((boolean|number)) → {boolean|number|MediaPlayer}

Sets or get value if media should be looping. Valid values are TRUE, FALSE, or a positive number how many times it should be looped. The stream continues even though video or audio repeats, after first iteration current time stops updating because it would show time of the total playback, not the current media time. If you need correct media progress time, implement your own loop by starting video again when it stops.

Parameters:

Name	Type	Description
`(boolean\|number)`		[loop] - Loop or not loop `boolean`, or a `number` how many times to loop.

Returns:

When setting value an instance of this object is returned, otherwise a current value is returned.

Type:: boolean | number | MediaPlayer

mute(mute) → {boolean|MediaPlayer}

Sets or gets the mute state of the media player audio. If muted, it will produce silence instead of provided sound. Its only used if audio stream is present.

Parameters:

Name	Type	Description
`mute`	boolean	`true` to mute, `false` to unmute.

Returns:

When setting value an instance of this object is returned, otherwise a current value is returned.

Type:: boolean | MediaPlayer

onPlayerEvents(callbackopt, removeopt) → {MediaPlayer}

Sets, removes, or gets the player component's events handlers.

Parameters:

Name	Type	Attributes	Description
`callback`	function	<optional>	Function that will handle the events.
`remove`	boolean	<optional>	`false` (Default) adds the handler. `true` removes the handler so it would no longer receive the events.

Returns:

Returns this component instance if adding or removing the handler, otherwise returns an array of added handler functions.

Type:: MediaPlayer

Example

// Example of PlayerEvent object
PlayerEvent {
    type: string,        // One of: `loadstart`, `loadedmetadata`, `seeking`, `timeupdate`, `play`, `stop`.
    mediaType: string,   // The type of media that is set to play in the player. One of: `File`, `InputDevice`, `URL`.
    media: Media,        // A Media formatted object that contains details about loaded media.
    currentTime: number, // Current play time.
    duration: number,    // Duration of the media in seconds. When event type is `timeupdate`.
    reason: string,      // Reason for stopping: `Control`, `EndOfMediaFile`, `EndOfAudioStream`, `EndOfVideoStream`, `EndOfErrorStream`, `Error`
}

// Example of a Media object
Media {
    duration: number,                    // Duration of the media in seconds. Present unless it's a live stream.
    videoStreams: VideoStream[],         // An array of detailed information about each available video stream.
    audioStreams: AudioStream[],         // An array of detailed information about each available audio stream.
    subtitleStreams: SubtitleStream[],   // An array of detailed information about each available subtitle stream.
}

// Example of a VideoStream object
VideoStream {
     sampleWidth: number,
     sampleHeight: number,
     width: number,
     height: number,
     pixelAspectRatio: string,
     displayAspectRatio: string,
     frameRate: number,
     codec: string,
     pixelFormat: string,
     progressive: boolean,
     default: boolean
}

// Example of a AudioStream object
AudioStream {
     sampleRate: number,
     channels: number,
     bitDepth: number,
     codec: string,
     default: boolean
}

// Example of a SubtitleStream object
SubtitleStream {
     language: string,
     codec: string,
     default: boolean
}

outputAudioDevice(deviceopt) → {MediaPlayer}

Sets or gets a current audio output device. To obtain a list of devices you can use "outputAudioDevices" getter property (e.g. player.outputAudioDevices) which returns a list of devices with their ID and formats. Device name or ID can be passed. Name is preferred, because when devices are added or removed, their ID may change, because it's just an index of the list of devices (enumerator). Name is more reliable, unless you have multiple devices with same name. In that case use ID.

Parameters:

Name	Type	Attributes	Description
`device`	object	<optional>	Audio output device object that contains device ID and format.

Returns:

Returns this component instance when setting, otherwise current audio output device info as an object.

Type:: MediaPlayer

pause() → {MediaPlayer}

Makes media player pause the playback.

Returns:

Returns this component instance.

Type:: MediaPlayer

play() → {MediaPlayer}

Makes the media player start media playback (assuming that media was previously specified using setFile(), setURL() or setInputDevice() functions).

Returns:

Returns this component instance.

Type:: MediaPlayer

seek(secondsopt) → {MediaPlayer}

Sets or gets current playing time in seconds. Decimal points are allowed (e.g. player.seek(165.43); ).

Parameters:

Name	Type	Attributes	Description
`seconds`	number	<optional>	Sets seek time in seconds. Two decimal points allowed for more precision.

Returns:

Returns this component instance.

Type:: MediaPlayer

setFile(path, videoStreamopt, audioStreamopt, subtitleStreamopt) → {MediaPlayer}

Sets a path of a local media file as a new media source. Resets player and overrides previously set source.

Parameters:

Name	Type	Attributes	Default	Description
`path`	string			Path to media file.
`videoStream`	number	<optional>	0	If the media file has more than one video stream, specify which one to use. Default is 0. For audio-only files this is ignored.
`audioStream`	number	<optional>	0	If the media file has more than one audio stream (such as multiple languages), specify which one to use. Default is 0. For media without audio stream this is ignored.
`subtitleStream`	number	<optional>	null	Index of a subtitle stream. There may be multiple streams in case of multiple languages. Default is NULL for no subtitles.

Returns:

Returns this component instance.

Type:: MediaPlayer

setInputDevice(videoDevice, audioDeviceopt) → {MediaPlayer}

Sets video device and audio device to use as video and audio source. Resets player and overrides previously set source. To get a list of available devices and their details you can use player.inputVideoDevices and player.inputAudioDevices getters where player is an instance of this MediaPlayer component.

Parameters:

Name	Type	Attributes	Default	Description
`videoDevice`	object		null	Video device object with optional specs. (Camera or video capture card). {id:string, size:string (WxH), fps:number (optional), pixel_format:string (optional)}. Set to NULL to omit video device.
`audioDevice`	object	<optional>	null	Audio device object with optional specs. {id:string, rate:number (optional), channels:number (optional, 1-Mono, 2-Stereo), bits:number(optional)}

Returns:

Returns this component instance.

Type:: MediaPlayer

setURL(url, videoStreamopt, audioStreamopt, formatopt, lowLatencyopt) → {MediaPlayer}

Sets URL of the media source. Resets player and overrides previously set source.

Parameters:

Name	Type	Attributes	Default	Description
`url`	string			URL of media.
`videoStream`	number	<optional>	0	If the media has more than one video stream, specify which one to use. Default is 0. For audio-only files this is ignored.
`audioStream`	number	<optional>	0	If the media has more than one audio stream (such as multiple languages), specify which one to use. Default is 0. For media without audio stream this is ignored.
`format`	string \| null	<optional>	null	Recommended to set for live video streams, such as web cam stream. This value is set as "-input_format" option for FFMPEG command. For example: mjpeg, rtsp, flv, mpegts, hls, http, https, srt or icecast.
`lowLatency`	boolean	<optional>	false	Set to TRUE to use ffmpeg options for low latency for live video streams (ffmpeg options such as low buffering).

Returns:

Returns this component instance.

Type:: MediaPlayer

stop() → {MediaPlayer}

Makes media player stop the playback. Seek time resets to 0, so play() function would start the playback from beginning.

Returns:

Returns this component instance.

Type:: MediaPlayer

visualizer(enable) → {boolean|MediaPlayer}

Sets or gets whether to show visualizer for audio-only streams (when no video stream is present, such as when playing music).

Parameters:

Name	Type	Description
`enable`	boolean	Use or not use visualizer for audio-only streams.

Returns:

When setting value an instance of this object is returned, otherwise a current value is returned.

Type:: boolean | MediaPlayer

(static) ffmpegPath(pathopt) → {boolean|string}

Sets the path to ffmpeg executable file, preferably absolute path. Default is ffmpeg, and it requires the path to ffmpeg to be added to Path environment variable. When setting path, boolean is returned whether path is valid and accepted. When getting value, string of previously specified or default value is returned.

Parameters:

Name	Type	Attributes	Description
`path`	string	<optional>	Path to the executable FFMPEG file. Default path is "ffmpeg".

Returns:

Returns string path when getting, or boolean when setting. boolean indicates if specified path was accepted (if it exists).

Type:: boolean | string