The state of an audio or video element as data, and the calls that play it, seek, load a source and set its rate and volume, which apply! also takes as data.
The functions take the element itself, so in a test any object with the element's attributes and methods stands in for it, e.g. an EventTarget in Node. The keys of the maps are the element's attributes in kebab-case, e.g. :current-time, and its numbered states are keywords, e.g. :have-metadata for HAVE_METADATA. The promises never reject, and each resolves to a map:
(-> (play! audio)
(.then prn))
;; prints {:playing true}, or e.g. {:refused :not-allowed}
The state of an audio or video element as data, and the calls that play
it, seek, load a source and set its rate and volume, which apply! also
takes as data.
The functions take the element itself, so in a test any object with the
element's attributes and methods stands in for it, e.g. an EventTarget in
Node. The keys of the maps are the element's attributes in kebab-case,
e.g. :current-time, and its numbered states are keywords, e.g.
:have-metadata for HAVE_METADATA. The promises never reject, and each
resolves to a map:
(-> (play! audio)
(.then prn))
;; prints {:playing true}, or e.g. {:refused :not-allowed}(apply! element effects)Apply the effects to the media element in order, and return a
promise of a vector of their answers, which never rejects.
The effects are one effect or a sequence of them. An effect is a
vector of a keyword and the arguments that the function it names takes
after the element, e.g. [:rate 1.5 {:preserves-pitch false}] for rate!:
An effect of another kind does nothing, and answers {:refused :unknown-effect}. In re-frame, register apply! as an effect:
(rf/reg-fx :media #(media/apply! audio %))
{:fx [[:media [[:seek 754] [:play]]]]}
Apply the `effects` to the media `element` in order, and return a
promise of a vector of their answers, which never rejects.
The `effects` are one effect or a sequence of them. An effect is a
vector of a keyword and the arguments that the function it names takes
after the element, e.g. [:rate 1.5 {:preserves-pitch false}] for rate!:
- [:play opts], play!
- [:pause], pause!
- [:seek position opts], seek!
- [:rate x opts], rate!
- [:volume level opts], volume!
- [:muted muted?], muted!
- [:source m], source!
- [:switch-source src], switch-source!
An effect of another kind does nothing, and answers {:refused
:unknown-effect}. In re-frame, register apply! as an effect:
(rf/reg-fx :media #(media/apply! audio %))
{:fx [[:media [[:seek 754] [:play]]]]}The curves from the position of a volume slider, from 0 to 1, to a volume, and back: :linear, and :cubic, which sounds even along the slider, as e.g. PulseAudio's does.
The curves from the position of a volume slider, from 0 to 1, to a volume, and back: :linear, and :cubic, which sounds even along the slider, as e.g. PulseAudio's does.
(error element)The error of the media element as a map of its :code and :message, or
nil while it has none, e.g. {:code :network}.
The error of the media `element` as a map of its :code and :message, or
nil while it has none, e.g. {:code :network}.The codes of a media element's error, by value.
The codes of a media element's error, by value.
The events of a media element that watch! follows by default.
The events of a media element that watch! follows by default.
(level x)(level x {:keys [curve] :or {curve :linear} :as opts})The position of a volume slider, from 0 to 1, for x, the state of a
media element from state or watch!, or the element itself, with the
opts below, e.g. 0.5 for a :volume of 0.125 on the :cubic curve. A
view that renders the state needs no element.
The position of a volume slider, from 0 to 1, for `x`, the state of a media element from state or watch!, or the element itself, with the `opts` below, e.g. 0.5 for a :volume of 0.125 on the :cubic curve. A view that renders the state needs no element. - :curve, one of curves, :linear by default
(muted! element muted?)Mute the media element, or unmute it where muted? is false, and
return e.g. {:muted true}.
Mute the media `element`, or unmute it where `muted?` is false, and
return e.g. {:muted true}.The network states of a media element, in the order of their values.
The network states of a media element, in the order of their values.
(pause! element)Pause the media element, and return {:paused true}.
Pause the media `element`, and return {:paused true}.
(play! element)(play! element {:keys [muted-fallback] :as opts})Play the media element, with the opts below, and return a promise of
the browser's answer:
The options:
Play the media `element`, with the `opts` below, and return a promise of
the browser's answer:
- {:playing true} once it plays
- {:refused :not-allowed} where the page may not play it, e.g. before
the user has clicked
- {:refused :not-supported} where its source won't play
- {:superseded true} where a pause or a new source came first
The options:
- :muted-fallback, true to play it muted where the browser refuses its
sound, which answers {:playing true :muted true}(ranges time-ranges)The time-ranges, a TimeRanges object, as a vector of [start end] in
seconds, e.g. [[0 812.4]].
The `time-ranges`, a TimeRanges object, as a vector of [start end] in seconds, e.g. [[0 812.4]].
(rate x)The playback rate nearest to x that every engine plays, from 1/16 to
16, or nil where x isn't a finite number.
The playback rate nearest to `x` that every engine plays, from 1/16 to 16, or nil where `x` isn't a finite number.
(rate! element x)(rate! element x {:keys [preserves-pitch] :as opts})Set the playback rate of the media element to x, with the opts
below, and return the rate as set, e.g. {:playback-rate 1.75}.
The call keeps the rate within 1/16 and 16, which every engine plays,
and returns x as :requested where it had to change it, e.g.
{:playback-rate 16 :requested 20}. A rate that isn't a finite number
leaves the rate as it was, and answers {:refused :not-finite}. The call
sets the default playback rate too, since a new source resets the rate
to it.
Set the playback rate of the media `element` to `x`, with the `opts`
below, and return the rate as set, e.g. {:playback-rate 1.75}.
The call keeps the rate within 1/16 and 16, which every engine plays,
and returns `x` as :requested where it had to change it, e.g.
{:playback-rate 16 :requested 20}. A rate that isn't a finite number
leaves the rate as it was, and answers {:refused :not-finite}. The call
sets the default playback rate too, since a new source resets the rate
to it.
- :preserves-pitch, false to let the pitch follow the rate, which every
engine keeps by defaultThe ready states of a media element, in the order of their values.
The ready states of a media element, in the order of their values.
(seek! element position)(seek! element position {:keys [fast] :as opts})Move the media element to the position in seconds, with the opts
below, and return the position as set, e.g. {:current-time 754}. A
position that isn't a finite number, e.g. a duration of nil before the
metadata, leaves the element where it was, and answers {:refused
:not-finite}.
Move the media `element` to the `position` in seconds, with the `opts`
below, and return the position as set, e.g. {:current-time 754}. A
position that isn't a finite number, e.g. a duration of nil before the
metadata, leaves the element where it was, and answers {:refused
:not-finite}.
- :fast, true to seek with fastSeek where the browser has it, which may
land near the position rather than on it, sooner, e.g. while a
scrubber is dragged(source! element {:keys [src position playback-rate] :as m})Load m, a map of a :src and the :position and :playback-rate to start
at, into the media element. Return m with the rate as set, e.g.
{:src "/272.mp3" :position 754 :playback-rate 1.5}. Other keys are left
alone, so m can be e.g. what podcast-clj's library/playback returns.
A new source pauses the element without a pause event and resets its rate. So the call sets the src first, then the position, which the element seeks to once the metadata has loaded, and then the rate with rate!.
Load `m`, a map of a :src and the :position and :playback-rate to start
at, into the media `element`. Return `m` with the rate as set, e.g.
{:src "/272.mp3" :position 754 :playback-rate 1.5}. Other keys are left
alone, so `m` can be e.g. what podcast-clj's library/playback returns.
A new source pauses the element without a pause event and resets its
rate. So the call sets the src first, then the position, which the
element seeks to once the metadata has loaded, and then the rate with
rate!.(state element)The state of the media element as a map of its attributes and its
:status, e.g.
{:status :buffering
:paused false
:ended false
:seeking false
:ready-state :have-current-data
:network-state :loading
:current-time 754.2
:duration 3600
:playback-rate 1.5
:muted false
:volume 1
:buffered [[0 812.4]]
:seekable [[0 3600]]
:played [[0 754.2]]
:error nil}
The :duration is nil until the metadata has loaded, rather than NaN, which isn't equal to itself, and ##Inf for a live stream. The :played ranges hold the seconds that were heard.
The state of the media `element` as a map of its attributes and its
:status, e.g.
{:status :buffering
:paused false
:ended false
:seeking false
:ready-state :have-current-data
:network-state :loading
:current-time 754.2
:duration 3600
:playback-rate 1.5
:muted false
:volume 1
:buffered [[0 812.4]]
:seekable [[0 3600]]
:played [[0 754.2]]
:error nil}
The :duration is nil until the metadata has loaded, rather than NaN,
which isn't equal to itself, and ##Inf for a live stream. The :played
ranges hold the seconds that were heard.(status {:keys [error ended paused network-state ready-state] :as state})The status of a media element, from state, a map of its attributes:
The status doesn't say whether the element plays, since :paused does, e.g. it plays while it's :ready and not :paused.
The status of a media element, from `state`, a map of its attributes: - :error, once it has failed - :ended, at the end - :buffering, while it waits for data to play, as HTML defines it for the :buffering pseudo-class - :idle, before it has the metadata - :ready, otherwise The status doesn't say whether the element plays, since :paused does, e.g. it plays while it's :ready and not :paused.
(switch-source! element src)Load src into the media element at its position and rate, e.g. for
another quality or format, and play it if it played. Return a promise of
the answer of play!, or of {:paused true} where it was paused.
Load `src` into the media `element` at its position and rate, e.g. for
another quality or format, and play it if it played. Return a promise of
the answer of play!, or of {:paused true} where it was paused.(volume! element level)(volume! element level {:keys [curve] :or {curve :linear} :as opts})Set the volume of the media element to the slider's level, from 0 to
1, with the opts below, and return the volume as set, e.g. {:volume
0.125} for a level of 0.5 on the :cubic curve.
The call keeps the level within 0 and 1, and returns the level as
:requested where it had to change it, e.g. {:volume 1 :requested 2}. A
level that isn't a finite number leaves the volume as it was, and
answers {:refused :not-finite}.
An iPhone plays every element at the system's volume, whatever the page sets, which volume-locked! tells.
Set the volume of the media `element` to the slider's `level`, from 0 to
1, with the `opts` below, and return the volume as set, e.g. {:volume
0.125} for a level of 0.5 on the :cubic curve.
The call keeps the level within 0 and 1, and returns the `level` as
:requested where it had to change it, e.g. {:volume 1 :requested 2}. A
level that isn't a finite number leaves the volume as it was, and
answers {:refused :not-finite}.
An iPhone plays every element at the system's volume, whatever the
page sets, which volume-locked! tells.
- :curve, one of curves, :linear by default(volume-locked!)A promise of whether the browser locks the volume of media elements at the system's, as an iPhone does, in which case a page's volume slider does nothing, or of nil outside a browser. It never rejects.
The call sets the volume of an element of its own, which it never plays, and waits half a second for the volumechange that a locked volume doesn't fire.
A promise of whether the browser locks the volume of media elements at the system's, as an iPhone does, in which case a page's volume slider does nothing, or of nil outside a browser. It never rejects. The call sets the volume of an element of its own, which it never plays, and waits half a second for the volumechange that a locked volume doesn't fire.
(watch! element f)(watch! element f {followed :events :or {followed events} :as opts})Call f with the state of the media element now and whenever it
changes, with the opts below, and return a function that stops it.
The call passes the map from state to f only when it differs from the
last, e.g.
(def stop!
(watch! audio #(swap! app assoc :player %)))
To know that the element has played to its end, e.g. to play the next episode, listen for its ended event. The state's :ended is also true after a seek to the end while it's paused, and Chrome has set :paused already by the first state in which :ended is true.
Call `f` with the state of the media `element` now and whenever it
changes, with the `opts` below, and return a function that stops it.
- :events, the events of the element to read its state at, as keywords,
by default events, which leaves out :timeupdate
The call passes the map from state to `f` only when it differs from the
last, e.g.
(def stop!
(watch! audio #(swap! app assoc :player %)))
To know that the element has played to its end, e.g. to play the next
episode, listen for its ended event. The state's :ended is also true
after a seek to the end while it's paused, and Chrome has set :paused
already by the first state in which :ended is true.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 |