The page's Media Session, which puts what plays on the lock screen and in the notifications, and lets the headphone buttons control it.
The functions that touch the browser do nothing where it has no Media Session, e.g. in Node or the Android WebView. Each takes these opts:
The keys of the maps are the members of the spec's dictionaries in kebab-case, and the values of its enums are keywords, e.g. {:action :seekto :seek-time 754.2}. A player whose buttons just play, pause and seek its media element needs three calls:
(def detach!
(attach! audio))
(metadata! {:title "Blue in Green" :artist "Miles Davis"})
(actions! (element-actions audio {:seekbackward 10
:seekforward 10}))
The page's Media Session, which puts what plays on the lock screen and
in the notifications, and lets the headphone buttons control it.
The functions that touch the browser do nothing where it has no Media
Session, e.g. in Node or the Android WebView. Each takes these opts:
- :session, the MediaSession to set instead of the page's, e.g. a
stand-in in a test, or nil for none
The keys of the maps are the members of the spec's dictionaries in
kebab-case, and the values of its enums are keywords, e.g. {:action
:seekto :seek-time 754.2}. A player whose buttons just play, pause and
seek its media element needs three calls:
(def detach!
(attach! audio))
(metadata! {:title "Blue in Green" :artist "Miles Davis"})
(actions! (element-actions audio {:seekbackward 10
:seekforward 10}))(action-effects {:keys [action fast-seek] :as details}
state
{:keys [ignore-seek-offset track-buttons] :as opts})The effects of media/apply! that the button press of details has on a
media element in state, as media/state gives it, with the opts of
element-actions, e.g. [[:seek 784]] for {:action :seekforward} at 754
with :seekforward 30. Play plays, pause and stop pause, and the seeks
go where seek-position says.
It's [] for an action that has no effect on the element, e.g. nexttrack without :track-buttons :skips, or a seek without a time, so a re-frame app can apply the effects of a press as data:
(rf/reg-fx :press
(fn [details]
(media/apply! audio (action-effects details
(media/state audio)
{:seekforward 30}))))
The effects of media/apply! that the button press of `details` has on a
media element in `state`, as media/state gives it, with the `opts` of
element-actions, e.g. [[:seek 784]] for {:action :seekforward} at 754
with :seekforward 30. Play plays, pause and stop pause, and the seeks
go where seek-position says.
It's [] for an action that has no effect on the element, e.g. nexttrack
without :track-buttons :skips, or a seek without a time, so a re-frame
app can apply the effects of a press as data:
(rf/reg-fx :press
(fn [details]
(media/apply! audio (action-effects details
(media/state audio)
{:seekforward 30}))))(actions! handlers)(actions! handlers opts)Set the handlers of the Media Session, a map of action to a function
of the details, with the opts above. Return the set of actions that
the browser refused, or nil where it has no Media Session.
A nil function clears its action, and so does leaving out an action that an earlier call set. The details are a map of the keys of MediaSessionActionDetails, e.g. {:action :seekto :seek-time 754.2}. Each engine refuses actions of its own, e.g. Firefox refuses those of video calls.
Set the `handlers` of the Media Session, a map of action to a function
of the details, with the `opts` above. Return the set of actions that
the browser refused, or nil where it has no Media Session.
A nil function clears its action, and so does leaving out an action that
an earlier call set. The details are a map of the keys of
MediaSessionActionDetails, e.g. {:action :seekto :seek-time 754.2}. Each
engine refuses actions of its own, e.g. Firefox refuses those of video
calls.(attach! element)(attach! element
{:keys [position-fn events actions]
:or {position-fn (constantly nil) events element-events}
:as opts})Keep the Media Session in step with the media element, with the opts
above and below, and return a function that detaches it.
The call watches the element with media/watch!, and sets the playback state and the position state that element-state returns for each new state. Detaching stops that, clears the position state, declares the playback state :none, and clears the handlers with :actions. Attaching another element detaches this one, since a page has one session.
Keep the Media Session in step with the media `element`, with the `opts`
above and below, and return a function that detaches it.
- :position-fn, a function from the element's state, as media/state
gives it, to its position state, e.g. element-position. Without it,
the position state stays clear, so that the browser follows the
element itself.
- :events, the events of the element to follow, by default
element-events
- :actions, the options of element-actions, e.g. {:seekbackward 15
:seekforward 30}, to set the element's own handlers too
The call watches the element with media/watch!, and sets the playback
state and the position state that element-state returns for each new
state. Detaching stops that, clears the position state, declares the
playback state :none, and clears the handlers with :actions. Attaching
another element detaches this one, since a page has one session.(clip-position {:keys [start end] :or {start 0} :as clip}
{:keys [current-time duration playback-rate] :as state})The position state of a clip of a media element, from clip, a map of
its :start and :end in seconds, e.g. from fragment/time, and state, a
map of the element's :current-time, :duration and :playback-rate. It's
nil while the end is unknown, which is the element's duration without
an :end.
As a :position-fn of attach!, it puts the clip on the lock screen rather than the whole file, e.g. 60 seconds of an hour. Its scrubber then gives times within the clip, so add the start to a :seek-time of seekto.
The position state of a clip of a media element, from `clip`, a map of its :start and :end in seconds, e.g. from fragment/time, and `state`, a map of the element's :current-time, :duration and :playback-rate. It's nil while the end is unknown, which is the element's duration without an :end. As a :position-fn of attach!, it puts the clip on the lock screen rather than the whole file, e.g. 60 seconds of an hour. Its scrubber then gives times within the clip, so add the start to a :seek-time of seekto.
(element-actions element)(element-actions element
{:keys [seekbackward seekforward track-buttons] :as opts})Handlers that play, pause, stop and seek the media element itself,
with the opts below. Stop pauses the element where it is.
Merge your own handlers over them before passing them to actions!. Keep seekto among them: Safari drops its own buttons once a page sets a handler, so without seekto its lock screen has no scrubber.
Each handler applies the effects that action-effects gives for the element's state at the press.
Handlers that play, pause, stop and seek the media `element` itself, with the `opts` below. Stop pauses the element where it is. - :seekbackward and :seekforward, the seconds of each skip, e.g. 15 and 30, where a skip without them is left out, since the spec has no default - :ignore-seek-offset, true to skip by those seconds even where the browser asks for others, e.g. the 15 that WebKit offers - :track-buttons, :skips to make previoustrack and nexttrack skip too, e.g. for the buttons of headphones Merge your own handlers over them before passing them to actions!. Keep seekto among them: Safari drops its own buttons once a page sets a handler, so without seekto its lock screen has no scrubber. Each handler applies the effects that action-effects gives for the element's state at the press.
The events of a media element that attach! listens to: those that change its duration or rate, make its position jump, start or stop it, give it a new source, or say that it failed.
The events of a media element that attach! listens to: those that change its duration or rate, make its position jump, start or stop it, give it a new source, or say that it failed.
(element-position {:keys [duration current-time playback-rate] :as state})The position state of a media element in state, a map of its
:duration, :current-time and :playback-rate, e.g. from media/state, or
nil while the duration is unknown.
The position state of a media element in `state`, a map of its :duration, :current-time and :playback-rate, e.g. from media/state, or nil while the duration is unknown.
(element-state position-fn {:keys [paused error] :as state})The :playback-state and :position-state that the session shows for a
media element in state, as media/state gives it. The position state
comes from position-fn, e.g. element-position.
An element that failed counts as paused, since a fatal error leaves its paused attribute false.
The :playback-state and :position-state that the session shows for a media element in `state`, as media/state gives it. The position state comes from `position-fn`, e.g. element-position. An element that failed counts as paused, since a fatal error leaves its paused attribute false.
(media-session opts)The MediaSession that the opts name as :session, or else the page's,
or nil where the browser has none.
The MediaSession that the `opts` name as :session, or else the page's, or nil where the browser has none.
(metadata m)(metadata m image-pred)The metadata m, a map of the keys of MediaMetadataInit, without what a
browser would throw for. That's the chapters whose :start-time is
negative, infinite or NaN, and the images that fail image-pred, by
default those without a :src.
The metadata `m`, a map of the keys of MediaMetadataInit, without what a browser would throw for. That's the chapters whose :start-time is negative, infinite or NaN, and the images that fail `image-pred`, by default those without a :src.
(metadata! m)(metadata! m opts)Show the metadata m, a map of the keys of MediaMetadataInit, in the
Media Session, or clear it for nil, with the opts above. Return the
metadata as set, or nil where the browser has no Media Session.
Before setting it, the call leaves out what the browser would throw for, i.e. what the function metadata leaves out and the images whose URL doesn't parse. A browser without chapters ignores them. Each change makes a new MediaMetadata, the one way that works alike in every engine, but setting the same metadata twice in a row does nothing.
Show the metadata `m`, a map of the keys of MediaMetadataInit, in the Media Session, or clear it for nil, with the `opts` above. Return the metadata as set, or nil where the browser has no Media Session. Before setting it, the call leaves out what the browser would throw for, i.e. what the function metadata leaves out and the images whose URL doesn't parse. A browser without chapters ignores them. Each change makes a new MediaMetadata, the one way that works alike in every engine, but setting the same metadata twice in a row does nothing.
(playback-state! state)(playback-state! state opts)Declare the playback state of the Media Session, :none, :paused or
:playing, with the opts above.
Declare the playback `state` of the Media Session, :none, :paused or :playing, with the `opts` above.
(position! state)(position! state opts)Show the position state, a map of the keys of MediaPositionState, in
the Media Session, or clear it for nil, with the opts above. Return the
state as set, or nil.
The call first corrects the state with position-state. If the browser still refuses it, e.g. an infinite duration in Safari and Firefox, the call clears the state, so that the browser follows the media element itself.
Show the position `state`, a map of the keys of MediaPositionState, in the Media Session, or clear it for nil, with the `opts` above. Return the state as set, or nil. The call first corrects the state with position-state. If the browser still refuses it, e.g. an infinite duration in Safari and Firefox, the call clears the state, so that the browser follows the media element itself.
(position-state {:keys [duration playback-rate position] :as m})The position state m, a map of its :duration, :playback-rate and
:position, as the browser takes it, or nil while the duration is
unknown.
The position stays within the duration, and a rate of 0, or one that isn't finite, counts as 1, since setPositionState throws for either. An infinite duration means a live stream.
The position state `m`, a map of its :duration, :playback-rate and :position, as the browser takes it, or nil while the duration is unknown. The position stays within the duration, and a rate of 0, or one that isn't finite, counts as 1, since setPositionState throws for either. An infinite duration means a live stream.
(previous-track position previous?)(previous-track position previous? seconds)What the previoustrack button does at position seconds into an item,
where previous? says whether an item comes before it: :previous within
the first seconds, 3 by default, as in Android's Media3, and otherwise
:restart, e.g. at 42 seconds.
What the previoustrack button does at `position` seconds into an item, where `previous?` says whether an item comes before it: :previous within the first `seconds`, 3 by default, as in Android's Media3, and otherwise :restart, e.g. at 42 seconds.
(seek-position {:keys [action seek-offset seek-time] :as details}
{:keys [current-time duration] :as state}
offsets)Where the seek action of details goes on a media element in state,
a map of its :current-time and :duration, with the offsets of
seekbackward and seekforward in seconds, e.g. {:seekbackward 15
:seekforward 30}.
An offset in the details goes first. The position stays between 0 and the duration, and it's nil for another action, or for a seek without a time or an offset.
Where the seek action of `details` goes on a media element in `state`,
a map of its :current-time and :duration, with the `offsets` of
seekbackward and seekforward in seconds, e.g. {:seekbackward 15
:seekforward 30}.
An offset in the details goes first. The position stays between 0 and
the duration, and it's nil for another action, or for a seek without a
time or an offset.(support!)(support! opts)What the Media Session supports, with the opts above, or nil where the
browser has none:
No browser lists its actions, but each throws for an action it lacks. So the first call for a session clears each action that the library hasn't set, and keeps those that don't throw. Call it before setting any handler yourself, outside the library.
What the Media Session supports, with the `opts` above, or nil where the browser has none: - :actions, the set of actions that it accepts - :position-state?, whether it accepts a position state - :chapter-info?, whether its metadata can have chapters No browser lists its actions, but each throws for an action it lacks. So the first call for a session clears each action that the library hasn't set, and keeps those that don't throw. Call it before setting any handler yourself, outside the library.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |