@byomakase/omakase-player v0.11.0-SNAPSHOT.1730420409
Omakase Player
Prerequisites
Omakase Player can be loaded as UMD module inside HTML page. If loaded as UMD module it requires hls.js loaded before Omakase Player:
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<script src="https://cdn.jsdelivr.net/npm/@byomakase/omakase-player@0.9.2-SNAPSHOT.1724678052/dist/omakase-player.umd.min.js"></script>
Omakase Player can be used as ES module and CJS module as well.
If used with modern Typescript / Javascript frameworks (such as Angular, React or Vue), it is recommended to simply install Omakase Player as dependency into package.json
:
npm install @byomakase/omakase-player
Optionally, you can include default Omakase Player CSS stylesheet or import and use omakase-player.scss
SCSS stylesheet.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@byomakase/omakase-player@0.9.2-SNAPSHOT.1724678052/dist/style.min.css">
Stylesheet references default player overlay icons, help menu icons and default styles for video safe zones. All of which can be overridden.
Player Initialization
Omakase Player requires div as a placeholder for HTML5 player.
<div id="omakase-player"></div>
Initialize the player by providing div id in player configuration. If used as UMD module, Omakase Player objects are available in global omakase
namespace:
// Create new OmakasePlayer instance
let omakasePlayer = new omakase.OmakasePlayer({
playerHTMLElementId: 'omakase-player',
});
Once player is initialized we can load hls video stream by providing stream URL and stream frame rate:
omakasePlayer.loadVideo('https://my-server.com/myvideo.m3u8', 25).subscribe({ // 25 - frame rate
next: (video) => {
console.log(`Video loaded. Duration: ${video.duration}, totalFrames: ${video.totalFrames}`)
}
})
Video API
Complete list of Video API methods is available in API Reference Docs
Video playback control
Video playback control is achieved through Video API.
// plays video
omakasePlayer.video.play().subscribe();
// pauses video
omakasePlayer.video.pause().subscribe();
// seeks to timestamp
omakasePlayer.video.seekToTime(123.45).subscribe({
next: (result) => {
if (result) {
console.log(`Seek to timestamp success`);
}
}
})
// seeks to frame
omakasePlayer.video.seekToFrame(123).subscribe({
next: (result) => {
if (result) {
console.log(`Seek to frame success`);
}
}
})
// toggles mute / unmute
omakasePlayer.video.toggleMuteUnmute();
Events
Before or after loading video stream, we can subscribe to various events. All events are available in API objects as Observables or we can subscribe to events by using EventEmmiter like methods. Example how to subscribe to video loaded event Observable:
// Subscribe to Observable
omakasePlayer.video.onVideoLoaded$.subscribe({
next: (event) => {
if (event) {
let video = event.video;
console.log(`Video loaded. Duration: ${video.duration}, totalFrames: ${video.totalFrames}`)
}
}
})
Example how to subscribe to video time change event using EventEmmiter like methods:
// alternatively, subscribe to events by using 'EventEmmiter' methods
omakasePlayer.on(omakasePlayer.EVENTS.OMAKASE_VIDEO_TIME_CHANGE, (event) => {
console.log(`Video time change. Timestamp: ${event.currentTime} => ${omakasePlayer.video.formatToTimecode(event.currentTime)}. Frame: ${event.frame}`)
})
Video playback events subscription examples:
omakasePlayer.video.onPlay$.subscribe({
next: (event) => {
console.log(`Video play. Timestamp: ${event.currentTime} => ${omakasePlayer.video.formatToTimecode(event.currentTime)}`)
}
})
omakasePlayer.video.onPause$.subscribe({
next: (event) => {
console.log(`Video pause. Timestamp: ${event.currentTime} => ${omakasePlayer.video.formatToTimecode(event.currentTime)}`)
}
})
omakasePlayer.video.onSeeked$.subscribe({
next: (event) => {
console.log(`Video seeked. Timestamp: ${event.currentTime} => ${omakasePlayer.video.formatToTimecode(event.currentTime)}`)
}
})
omakasePlayer.video.onVideoTimeChange$.subscribe({
next: (event) => {
console.log(`Video time change. Timestamp: ${event.currentTime} => ${omakasePlayer.video.formatToTimecode(event.currentTime)}. Frame: ${event.frame}`)
}
})
Hls.js
We can fetch hls.js instance through API, as well as subscribe to hls.js events:
// Get hls.js instance and hook onto hls.js events
let hlsInstance = omakasePlayer.video.getHls();
hlsInstance.on('hlsManifestParsed', (event, data) => {
console.log(`HLS manifest parsed`, data);
})
Utilities
// adds safe zone 10% from all player edges
omakasePlayer.video.addSafeZone({
topRightBottomLeftPercent: [10, 10, 10, 10]
})
// adds safe zone calculated from provided aspect ratio expression
omakasePlayer.video.addSafeZone({
aspectRatio: "16/9"
})
// toggles fullscreen
omakasePlayer.video.toggleFullscreen();
Audio API
Complete list of Audio API methods is available in API Reference Docs.
Few common usages of Audio API:
// retrieves all available audio tracks
let audioTracks = omakasePlayer.audio.getAudioTracks();
// retrieves active audio track
let activeAudioTrack = omakasePlayer.audio.getActiveAudioTrack();
// detect audio tracks switching
omakasePlayer.audio.onAudioSwitched$.subscribe({
next: (event) => {
console.log(`Audio switched`, event)
}
})
// sets another audio track as active
omakasePlayer.audio.setActiveAudioTrack(audioTracks[1].id);
Timeline
Timeline is initialized by defining div placeholder and calling createTimeline()
API method with optional configuration and style settings.
<div id="omakase-timeline"></div>
omakasePlayer.createTimeline({
// html timeline div id
timelineHTMLElementId: 'omakase-timeline',
// thumbnails can be loaded from VTT file and shown in Timeline Scrubber Lane on mouse hover
thumbnailVttUrl: 'https://my-server.com/thumbnails/timeline.vtt',
style: {
stageMinHeight: 300,
backgroundFill: '#fef9f7'
// ...see API Reference Docks for all other available style properties
}
}).subscribe({
next: (timelineApi) => {
console.log(`Timeline loaded`)
}
})
Timeline Lanes
Omakase Player supports adding various Timeline Lanes:
- Scrubber Lane
- Thumbnail Lane
- Marker Lane
- Subtitles Lane
- Audio Track Lane
- Label Lane
- Scrollbar Lane
- Line Chart Lane
- Bar Chart Lane
- Og Chart Lane
Timeline Lanes are added after Timeline creation. Base Timeline Lanes can be configured, styled and extended with custom functionalities.
Scrubber Lane
Scrubber Lane is created automatically. Scrubber Lane instance can be fetched by using Timeline API after Timeline is created
omakasePlayer.createTimeline().subscribe({
next: (timelineApi) => {
console.log(`Timeline loaded`);
let scrubberLane = omakasePlayer.timeline.getScrubberLane();
// set custom styles for Scrubber Lane
scrubberLane.style = {
backgroundFill: '#dfe0e2',
tickFill: '#08327d',
timecodeFill: '#08327d'
// ...see API Reference Docks for all other available style properties
}
}
})
Thumbnail Lane
Thumbnail Lane loads thumbnails from VTT file and shows them on timeline. In example below thumbnail mouse click event is handled.
let thumbnailLane = new omakase.ThumbnailLane({
description: 'Thumbnails',
vttUrl: 'https://my-server.com/thumbnails.vtt'
})
omakasePlayer.timeline.addTimelineLane(thumbnailLane);
// Handle thumbnail click event
thumbnailLane.onClick$.subscribe({
next: (event) => {
if (event.thumbnail.cue) {
console.log(`Seeking to to thumbnail: ${omakasePlayer.video.formatToTimecode(event.thumbnail.cue.startTime)}`);
omakasePlayer.video.seekToTime(event.thumbnail.cue.startTime).subscribe({
next: () => {
console.log(`Seek complete`);
}
})
}
}
})
Marker Lane
Marker Lane can be populated from VTT file or by using API methods directly:
// marker lane
let markerLane = new omakase.MarkerLane({
description: 'Markers',
vttUrl: 'https://demo.player.byomakase.org/data/thumbnails/timeline.vtt', // https://my-server.com/thumbnails/timeline.vtt
markerCreateFn: (cue, index) => {
return new omakase.PeriodMarker({
timeObservation: {
start: cue.startTime,
end: cue.endTime
},
text: `${cue.text}`,
editable: true,
style: {
renderType: 'lane',
color: index % 2 ? '#2677bb' : '#dd6464',
symbolType: 'triangle'
}
})
},
markerProcessFn: (marker, index) => {
marker.onClick$.subscribe({
next: (event) => {
console.log(`Clicked on marker with text: `, marker.text)
}
})
marker.onChange$.subscribe({
next: (event) => {
console.log(`Marker time observation change: `, event)
}
})
}
})
omakasePlayer.timeline.addTimelineLane(markerLane);
// manually adding markers through API
markerLane.addMarker(new omakase.MomentMarker({
timeObservation: {
time: 100
},
style: {
renderType: 'spanning',
color: '#ff0000',
symbolType: 'circle'
}
}));
Subtitles Lane
Subtitles Lane is used for subtitles visualisation on timeline. It is populated from VTT file.
let subtitlesLane = new omakase.SubtitlesLane({
description: 'Subtitles',
vttUrl: 'https://my-server.com/subtitles.vtt'
})
omakasePlayer.timeline.addTimelineLane(subtitlesLane);
Audio Track Lane
Audio Track Lane is used for audio track visualisation.
let audioTrackLane = new omakase.AudioTrackLane({
description: 'Audio Track',
vttUrl: 'https://my-server.com/audio-track.vtt'
})
omakasePlayer.timeline.addTimelineLane(audioTrackLane);
Label Lane
Label Lane is usually used on timeline as grouping lane that contains other timeline components, such as timeline buttons and labels.
let labelLane = new omakase.LabelLane({
description: 'Label lane', // appears in left pane
text: 'Right pane label', // appears in right pane
style: {
backgroundFill: '#a5a6a9',
textFill: '#f45844',
textFontSize: 20
}
});
omakasePlayer.timeline.addTimelineLane(labelLane);
Scrollbar Lane
Scrollbar Lane contains Timeline scrollbar that controls timeline zoom and scroll.
// scrollbar lane
let scrollbarLane = new omakase.ScrollbarLane({
description: ''
});
omakasePlayer.timeline.addTimelineLane(scrollbarLane);
Line Chart Lane
Line Chart Lane for data visualisation.
let lineChartLane = new omakase.LineChartLane({
vttUrl: 'https://my-server.com/line-chart.vtt',
yMax: 100, // optional custom max value, if not provided it will be resolved from data
yMin: -50, // optional custom min value, if not provided it will be resolved from data
style: {
pointWidth: 5,
lineStrokeWidth: 2
},
});
omakasePlayer.timeline.addTimelineLane(lineChartLane);
Bar Chart Lane
Bar Chart Lane for data visualisation.
let barChartLane = new omakase.BarChartLane({
vttUrl: 'https://my-server.com/bar-chart.vtt',
description: 'Bar Chart',
valueMax: 120, // optional custom max value, if not provided it will be resolved from data
valueMin: 50, // optional custom min value, if not provided it will be resolved from data
valueTransformFn: (value) => {
// each value can be transformed in this hook function
return value;
},
itemProcessFn: (item, index) => {
// each chart item can be processed in this hook function
item.onClick$.subscribe({
next: (event) => {
console.log(event, item)
}
})
},
valueInterpolationStrategy: 'max' // average - take interpolated points average | max - take interpolated points max
});
omakasePlayer.timeline.addTimelineLane(barChartLane);
OG Chart Lane
OG Chart Lane for data visualisation.
let ogChartLane = new omakase.OgChartLane({
vttUrl: 'https://my-server.com/og-chart.vtt',
description: 'Bar Chart',
valueMax: 120, // optional custom max value, if not provided it will be resolved from data
valueMin: 50, // optional custom min value, if not provided it will be resolved from data
valueTransformFn: (value) => {
// each value can be transformed in this hook function
return value;
},
itemProcessFn: (item, index) => {
// each chart item can be processed in this hook function
item.onClick$.subscribe({
next: (event) => {
console.log(event, item)
}
})
},
valueInterpolationStrategy: 'max' // average - take interpolated points average | max - take interpolated points max
});
omakasePlayer.timeline.addTimelineLane(ogChartLane);
Timeline Lane API
Timeline Lane Nodes
Timeline Lane Nodes can be added to Timeline Lane instances with addTimelineNode()
API method. Nodes types that can be added are:
- Image button
- Text label
In this example, Timeline zoom in and zoom out buttons are added to Scrubber Lane:
let scrubberLane = omakasePlayer.timeline.getScrubberLane();
// define zoom in button
let zoomInButton = new omakase.ImageButton({
src: `https://my-server.com/images/plus-circle.svg`,
width: 30,
height: 30,
listening: true // set to true if button is interactive
})
// handle click event
zoomInButton.onClick$.subscribe({
next: (event) => {
omakasePlayer.timeline.zoomInEased().subscribe();
}
})
// define zoom out button
let zoomOutButton = new omakase.ImageButton({
src: `https://my-server.com/images/minus-circle.svg`,
width: 30,
height: 30,
listening: true
})
// handle click event
zoomOutButton.onClick$.subscribe({
next: (event) => {
omakasePlayer.timeline.zoomOutEased().subscribe();
}
});
// add buttons to scrubber lane
[zoomOutButton, zoomInButton].forEach(button => {
scrubberLane.addTimelineNode({
width: button.config.width,
height: button.config.height,
justify: 'end',
timelineNode: button,
})
});
Minimize, Maximize
Timeline Lane in Timeline can be minimized or maximized by calling methods from TimelineLaneApi
.
In this example, Grouping Label Lane is created at specific index on Timeline. Minimize and Maximize Text Label action buttons are created and added to Timeline Lane left pane.
// marker lane group
let markerLaneGroup = new omakase.LabelLane({
text: 'Marker Lane Group', // appears in right pane
style: {
backgroundFill: '#c2b4a6',
textFill: '#fbfbfb'
}
});
// add grouping lane before MarkerLane
omakasePlayer.timeline.addTimelineLaneAtIndex(markerLaneGroup, omakasePlayer.timeline.getTimelineLanes().findIndex(p => p.id === markerLane.id));
// minimize text label
let textLabelMinimize = new omakase.TextLabel({
text: `Minimize`,
listening: true,
style: {
align: 'center',
verticalAlign: 'middle',
fill: '#ffffff',
backgroundFill: '#f45844',
backgroundBorderRadius: 3
}
});
// maximize text label
let textLabelMaximize = new omakase.TextLabel({
text: `Maximize`,
listening: true,
style: {
align: 'center',
verticalAlign: 'middle',
fill: '#ffffff',
backgroundFill: '#46454b',
backgroundBorderRadius: 3
}
});
// minimize lane on click
textLabelMinimize.onClick$.subscribe({
next: () => {
if (!markerLane.isMinimized()) {
markerLane.minimizeEased().subscribe()
}
}
})
// maximize lane on click
textLabelMaximize.onClick$.subscribe({
next: () => {
if (markerLane.isMinimized()) {
markerLane.maximizeEased().subscribe()
}
}
});
// add text labels to grouping lane left pane
[textLabelMinimize, textLabelMaximize].forEach(textLabel => {
markerLaneGroup.addTimelineNode({
width: 60,
height: 22,
justify: 'start',
margin: [0, 5, 0, 0],
timelineNode: textLabel
});
})
Marker List API
A marker list can be added with the createMarkerList()
API method.
The marker list web component will be added into a html element with id defined in markerListHTMLElementId
. If this parameter is not provided, it will default toomakase-player-marker-list
.
Thumbnail VTT file can be passed with thumbnailVttFile
. If provided, it will be used to automatically set the thumbnail to the closest vtt cue based on the marker start time.
You can also provide thumbnailFn
to define a function that provides a thumbnail url for any given time.
omakasePlayer.createMarkerList({
markerListHTMLElementId: 'marker-list',
thumbnailVttFile: omakasePlayer.timeline.thumbnailVttFile
})
Markers can be added to the marker list using the method addMarker()
, updated using the method updateMarker()
or removed from the marker list using the method removeMarker()
. Marker can be toggled on the list as active using the method toggleMarker()
.
omakasePlayer.createMarkerList().subscribe(markerList => {
// add marker
const marker = markerList.addMarker({
name: 'Marker',
timeObservation: {
start: 100,
end: 200
},
style: {
color: 'red'
}
})
// update marker
markerList.updateMarker(marker.id, { color: 'blue' })
// set marker as active/inactive
markerList.toggleMarker(marker.id)
// remove marker
markerList.removeMarker(marker.id)
})
Marker list HTML and style can be customised by passing a css file url and template element ids.
A template for the marker list row can include slots to render data or trigger actions. Beside predefined slots (color
, thumbnail
, name
, track
, start
, end
, duration
, remove
), dynamic slots can be used to display custom data or trigger custom actions. Custom data slots must be prefixed with data-
and custom actions slots must be prefixed with action-
.
The parameter styleUrl
can be an array to provide multiple css files.
omakasePlayer.createMarkerList({
templateHTMLElementId: 'row-template';
headerHTMLElementId: 'header-template';
emptyHTMLElementId: 'empty-template';
styleUrl: './style.css';
})
<template id="row-template">
<div slot="color"></div>
<div slot="name"></div>
<div slot="start"></div>
<div slot="end"></div>
<div class="actions">
<span slot="action-edit"></span>
<span slot="remove"></span>
</div>
</template>
<template id="header-template">
<!-- header content -->
</template>
<template id="empty-template">
<!-- content to render if marker list is empty -->
</template>
A marker list can be loaded from a VTT file. In this case a function to create a marker list item from VTT file cues can also be provided, as well as HTML content to render while the file is loading.
const colors = ['red', 'green', 'blue']
omakasePlayer.createMarkerList({
loadingHTMLElementId: 'loading-template';
vttUrl: './markers.vtt',
vttMarkerCreateFn: (cue, index) => ({
name: 'VTT Marker ' + index,
timeObservation: {
start: cue.startTime,
end: cue.endTime
},
style: {
color: colors[index % colors.length]
},
data: {
custom_key: 'custom value'
}
})
})
<template id="loading-template">
<!-- content to render while the VTT file is loading -->
</template>
Marker list can also be linked to one or multiple timeline lanes. If linked in this way, the markers from the timeline lane(s) will appear on the marker list.
omakasePlayer.createMarkerList({
source: [
omakasePlayer.timeline.getTimelineLane('marker-lane-1'),
omakasePlayer.timeline.getTimelineLane('marker-lane-2')
]
})
Marker list provides onMarkerClick$
and onMarkerAction$
events. onMarkerClick$
is triggered when the marker list item row is clicked and onMarkerAction$
is triggered when a custom element provided with an action-<name>
slot is clicked.
There are also marker lifecycle events onMarkerCreate$
, onMarkerUpdate$
, onMarkerDelete$
and onMarkerInit$
(which is triggered after markers are initialized from the source or vtt file).
omakasePlayer.createMarkerList().subscribe(markerList => {
markerList.onMarkerClick$.subscribe(event => {
console.log(event.marker)
})
markerList.onMarkerAction$.subscribe(event => {
console.log(event.action, event.marker)
})
})
Marker list can be destroyed with the destroy()
method. This cleans up the marker list resources and removes it from the DOM.
Subtitles API
Complete list of Audio API methods is available in API Reference Docs.
Omakase Player automatically identifies all available subtitles VTT tracks from stream manifest and makes them available through Subtitles API.
omakasePlayer.subtitles.onSubtitlesLoaded$.subscribe({
next: (event) => {
// retrieves all subtitles VTT tracks
let subtitlesVttTracks = omakasePlayer.subtitles.getTracks();
// shows first available VTT track
omakasePlayer.subtitles.showTrack(subtitlesVttTracks[0].id)
}
})
Subtitles can be imported from external VTT file:
// import subtitles from VTT file
omakasePlayer.subtitles.createVttTrack({
id: '0',
src: 'https://my-server.com/subtitles.vtt',
label: 'English (US)',
language: 'en-us',
default: true
}).subscribe({
next: (subtitlesVttTrack) => {
console.log(`Subtitles successfully created`)
}
})
Development
Player build & build watch
npm install ci
npm run dev
Production build
npm install ci
npm run prod
Production artefacts that need to be published to NPM are created in /dist
folder
Known limitations
- Firefox browser is not supported as it doesn't support
requestVideoFrameCallback
function
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
10 months ago
9 months ago
10 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
10 months ago
9 months ago
9 months ago
10 months ago
10 months ago
9 months ago
9 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
11 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
11 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
11 months ago
10 months ago
10 months ago
11 months ago
10 months ago
11 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
1 year ago
1 year ago
1 year ago
12 months ago
11 months ago
1 year ago
1 year ago
12 months ago
1 year ago
1 year ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
12 months ago
1 year ago
1 year ago
11 months ago
12 months ago
1 year ago
12 months ago
11 months ago
1 year ago
1 year ago
12 months ago
11 months ago
11 months ago
12 months ago
1 year ago
11 months ago
11 months ago
12 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
12 months ago
1 year ago
1 year ago
12 months ago
1 year ago
1 year ago
1 year ago
12 months ago
1 year ago
1 year ago
1 year ago
12 months ago
1 year ago
1 year ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
12 months ago
12 months ago
1 year ago
12 months ago
11 months ago
1 year ago
11 months ago
11 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago