HTML::O...t::Media(3)

📦 version 0.6.0, in alpine 3.24

💖 NAME 💖

HTML::O...t::Media(3) is the manual page name, and yes bestie, it's the User Contributed Perl Documentation page for HTML::Object::DOM::Element::Media — the HTML Object DOM Media Class. Iconic class name, honestly.

🎀 SYNOPSIS 🎀

use HTML::Object::DOM::Element::Media;
my $media = HTML::Object::DOM::Element::Media->new ||
    die( HTML::Object::DOM::Element::Media->error, "\n" );

⭐ VERSION ⭐

v0.2.0

🦋 DESCRIPTION 🦋

Okay so this interface adds stuff onto HTML::Object::DOM::Element — specifically the properties and methods you need for the basic media-related capabilities that audio and video have in common. It's giving “one class to handle the media vibes,” periodt.

👑 INHERITANCE 👑

The ancestry chain, in all its ASCII-art glory:

+-----------------------+     +---------------------------+     +-------------------------+     +----------------------------+     +-----------------------------------+
| HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::Node | --> | HTML::Object::DOM::Element | --> | HTML::Object::DOM::Element::Media |
+-----------------------+     +---------------------------+     +-------------------------+     +----------------------------+     +-----------------------------------+

💅 PROPERTIES 💅

It inherits properties from its parent HTML::Object::DOM::Element. Naturally. Main character inheritance energy.

🎧 audioTracks 🎧

An AudioTrackList that lists the AudioTrack objects contained in the element. Yes, it's a whole list situation.

Example:

my $video = $doc->getElementById("video");

for( my $i = 0; $i < $video->audioTracks->length; $i += 1 )
{
    $video->audioTracks->[$i]->enabled = 0; # false
}

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/audioTracks

✨ autoplay ✨

A boolean value that reflects the "autoplay" HTML attribute, indicating whether playback should automatically begin as soon as enough media is available to do so without interruption.

🚨 Note: Automatically playing audio when the user does not expect or desire it is a poor user experience and should be avoided in most cases, though there are exceptions. See the Mozilla Autoplay guide for media and Web Audio APIs https://developer.mozilla.org/en-US/docs/Web/Media/Autoplay_guide for more information. Keep in mind that browsers may ignore autoplay requests, so you should ensure that your code is not dependent on "autoplay" working.

Example:

<video id="video" autoplay="" controls>
    <source src="https://player.vimeo.com/external/250688977.sd.mp4?s=d14b1f1a971dde13c79d6e436b88a6a928dfe26b&profile_id=165">
</video>

# *** Disable autoplay (recommended) ***
# false is the default value
$doc->querySelector('#video')->autoplay = 0; # false
# <video id="video" controls>

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/autoplay

🌸 buffered 🌸

This returns "undef" under perl.

Normally, under JavaScript, this returns a "TimeRanges" object that indicates the ranges of the media source that the browser has buffered (if any) at the moment the buffered property is accessed.

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/buffered

🦋 controller 🦋

This returns "undef" under perl.

Normally, under JavaScript, this returns a "MediaController" object that represents the media controller assigned to the element, or "undef" if none is assigned.

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/controller

🎀 controls 🎀

Is a boolean that reflects the controls HTML attribute, indicating whether user interface items for controlling the resource should be displayed.

Example:

my $obj = $doc->createElement('video');
$obj->controls = 1; # true

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/controls

👑 controlsList 👑

Returns a HTML::Object::TokenList that helps the user agent select what controls to show on the media element whenever the user agent shows its own set of controls. The HTML::Object::TokenList takes one or more of three possible values: "nodownload", "nofullscreen", and "noremoteplayback".

Example:

To disable the download button for HTML5 audio and video player:

<audio controls controlsList="nodownload"><source src="song.mp3" type="audio/mpeg"></audio>

<video controls controlsList="nodownload"><source src="video.mp4" type="video/mp4"></video>

Another example:

<video controls controlsList="nofullscreen nodownload noremoteplayback"></video>

Using code:

my $video = $doc->querySelector('video');
$video->controls; # true
$video->controlsList; # ["nofullscreen", "nodownload", "noremoteplayback"]
$video->controlsList->remove('noremoteplayback');
$video->controlsList; # ["nofullscreen", "nodownload"]
$video->getAttribute('controlsList'); # "nofullscreen nodownload"

# Actually, under perl, 'supports' always returns true
$video->controlsList->supports('foo'); # false
$video->controlsList->supports('noremoteplayback'); # true

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/controlsList, and Chromium documentation: https://developers.google.com/web/updates/2017/03/chrome-58-media-updates

🌈 crossOrigin 🌈

A string indicating the CORS setting for this media element.

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/crossOrigin

⭐ currentSrc ⭐

Returns a string with the absolute URL of the chosen media resource.

Example:

my $obj = $doc->createElement('video');
say($obj->currentSrc); # ""

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/currentSrc

💜 currentTime 💜

This returns whatever number you set it to under perl, as a Module::Generic::Number object.

Normally, under JavaScript, this returns a double-precision floating-point value indicating the current playback time in seconds; if the media has not started to play and has not been seeked, this value is the media's initial playback time. Setting this value seeks the media to the new time. The time is specified relative to the media's timeline.

Example:

my $video = $doc->createElement('$video');
say( $video->currentTime );
$vide->currentTime = 35;

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/currentTime

🎀 defaultMuted 🎀

A Boolean that reflects the "muted" HTML attribute, which indicates whether the media element's audio output should be muted by default.

Example:

my $video = $doc->createElement('video');
$video->defaultMuted = 1; # true
say( $video->outerHTML ); # <video muted=""></video>

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/defaultMuted

🦋 defaultPlaybackRate 🦋

This returns whatever number you set it to under perl, as a Module::Generic::Number object.

Normally, under JavaScript, this returns a double indicating the default playback rate for the media.

Example:

my $obj = $doc->createElement('video');
say($obj->defaultPlaybackRate); # 1

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/defaultPlaybackRate

✨ disableRemotePlayback ✨

A boolean that sets or returns the remote playback state of the HTML attribute, indicating whether the media element is allowed to have a remote playback UI.

Example:

my $obj = $doc->createElement('audio');
# <audio></audio>
$obj->disableRemotePlayback = 1; # true
# <audio disableremoteplayback=""></audio>

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/disableRemotePlayback

🌸 duration 🌸

This returns whatever number you set it to under perl, as a Module::Generic::Number object.

Normally, under JavaScript, this returns a read-only double-precision floating-point value indicating the total duration of the media in seconds. If no media data is available, the returned value is "NaN". If the media is of indefinite length (such as streamed live media, a WebRTC call's media, or similar), the value is "+Infinity".

Example:

my $obj = $doc->createElement('video');
say( $obj->duration ); # NaN

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/duration

🎧 ended 🎧

Returns a Boolean that indicates whether the media element has finished playing.

Example:

my $obj = $doc->createElement('video');
say($obj->ended); # false

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/ended

🚨 error 🚨

Read-only.

This returns a HTML::Object::MediaError object for the most recent error, or "undef" if there has not been an error.

Example:

my $video = $doc->createElement('video');
$video->onerror = sub
{
    say( "Error " . $video->error->code . "; details: " . $video->error->message );
}
$video->src = 'https://example.org/badvideo.mp4';

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/error

🔁 loop 🔁

A Boolean that reflects the "loop" HTML attribute, which indicates whether the media element should start over when it reaches the end.

Example:

my $obj = $doc->createElement('video');
$obj->loop = 1; # true

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/loop

🔑 mediaKeys 🔑

This always returns "undef" under perl.

Normally, under JavaScript, this returns a MediaKeys object (https://developer.mozilla.org/en-US/docs/Web/API/MediaKeys) or "undef". MediaKeys (https://developer.mozilla.org/en-US/docs/Web/API/MediaKeys) is a set of keys that an associated HTML::Object::DOM::Element::Media can use for decryption of media data during playback.

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/mediaKeys

🔇 muted 🔇

Is a boolean that determines whether audio is muted. true if the audio is muted and false otherwise. This does not affect the DOM.

Example:

my $obj = $doc->createElement('video');
say( $obj->muted ); # false

🦋 See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/muted

🌐 networkState 🌐

Set or get an integer (enumeration) indicating the current state of fetching the media over the network.

Example:

<audio id="example" preload="auto">
    <source src="sound.ogg" type="audio/ogg" />
</audio>

# Export constants
use HTML::Object::DOM::Element::Media qw( :all );
my $obj = $doc->getElementById('example');
$obj->addEventListener( playing => sub
{
    if( $obj->networkState == NETWORK_LOADING )
    {
        # Still loading...
    }
});

Peep "CONSTANTS" below for the constants that you can export and actually use, bestie 💅

Also, if you wanna go deeper, the Mozilla docs live here: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/networkState

paused 🍓

Returns a boolean, and it's telling you whether the media element is paused. Set to true when you call the pause method, and set to false when you call the play method. That's it, that's the whole vibe check 🫶

Example, because you know we love one:

my $obj = $doc->createElement('video');
say( $obj->paused ); # true

Mozilla ref if you want it: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/paused

playbackRate 🔥

Heads up: under perl, this just sets or gets a number. That's the whole situation.

Under JavaScript normally, this is a double that tells you the rate the media is being played back at. Same idea, different language energy 😌

Example:

my $obj = $doc->createElement('video');
say( $obj->playbackRate ); # Expected Output: 1

Mozilla ref: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/playbackRate

played 💀

This one always returns undef under perl. No cap. It's just not a thing for us 😭

Under JavaScript normally, it returns a TimeRanges object that holds the ranges of the media source the browser has played, if any.

TimeRanges docs, if you're curious: https://developer.mozilla.org/en-US/docs/Web/API/TimeRanges

Mozilla ref for the property itself: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/played

preload 🎀

It's a string that reflects the preload HTML attribute, telling you what data should be preloaded — if any. The possible values are straight up: none, metadata, auto. Iconic trio ✨

Mozilla ref: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/preload

preservesPitch 🦋

Under perl, this is literally just a boolean value you can set or get. Simple queen behaviour.

Under JavaScript, it's a boolean that decides whether the pitch of the sound will be preserved. If you set it to false, the pitch will adjust to the speed of the audio. It's implemented with prefixes in Firefox (mozPreservesPitch) and WebKit (webkitPreservesPitch) — the drama of it all 💅

Mozilla ref: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/preservesPitch

readyState ⭐

Set or get an integer (it's an enumeration, fancy) that shows the readiness state of the media.

Example:

<audio id="example" preload="auto">
    <source src="sound.ogg" type="audio/ogg" />
</audio>

use HTML::Object::DOM::Element::Media qw( :all );
my $obj = $doc->getElementById('example');
$obj->addEventListener( loadeddata => sub
{
    if( $obj->readyState >= NETWORK_LOADING )
    {
        $obj->play();
    }
});

Check out "CONSTANTS" for the constants you can export and use 👑

Mozilla ref: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/readyState

seekable 🌸

Always returns undef under perl, bestie. Sorry 😭

Under JavaScript normally, it returns a TimeRanges object containing the time ranges the user can seek to, if any.

TimeRanges docs: https://developer.mozilla.org/en-US/docs/Web/API/TimeRanges

Mozilla ref: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/seekable

seeking 🧚

Under perl, this is just a boolean you can set or get. That's the entire plot.

Under JavaScript, it's a boolean that says whether the media is currently in the process of seeking to a new position — the "hold on, I'm looking for it" era 🙈

Mozilla ref: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/seeking

sinkId 🎧

Returns undef by default under perl. If you want a value in there, you gotta set one using setSinkId.

Normally under JavaScript, it returns a string that's the unique ID of the audio device delivering output — or an empty string if it's using the user agent default. That ID should be one of the MediaDeviceInfo.deviceid values returned from MediaDevices.enumerateDevices(), id-multimedia, or id-communications. Whole lotta IDs, I know 💀

Mozilla ref: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/sinkId

src 🌈

It's a string that reflects the src HTML attribute, which holds the URL of a media resource to use. The main character of attributes, honestly ✨

Example:

my $obj = $doc->createElement('video');
say( $obj->src ); # ""

Mozilla ref: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/src

srcObject 💜

Always returns undef under perl. Periodt.

Normally under JavaScript, this is a MediaStream representing the media to play or that has played in the current HTML::Object::DOM::Element::Media — or undef if nothing has been assigned.

MediaStream docs: https://developer.mozilla.org/en-US/docs/Web/API/MediaStream

Mozilla ref: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/srcObject

textTracks 📝

Read-only. Don't come for her, she's not taking edits 💅

Returns the list of TextTrack objects contained in the element.

Example — yes there are ten tracks, yes it's a lot, stay with me:

<video controls poster="/images/sample.gif">
    <source src="sample.mp4" type="video/mp4">
    <source src="sample.ogv" type="video/ogv">
    <track kind="captions" src="sampleCaptions.vtt" srclang="en">
    <track kind="descriptions" src="sampleDescriptions.vtt" srclang="en">
    <track kind="chapters" src="sampleChapters.vtt" srclang="en">
    <track kind="subtitles" src="sampleSubtitles_de.vtt" srclang="de">
    <track kind="subtitles" src="sampleSubtitles_en.vtt" srclang="en">
    <track kind="subtitles" src="sampleSubtitles_ja.vtt" srclang="ja">
    <track kind="subtitles" src="sampleSubtitles_oz.vtt" srclang="oz">
    <track kind="metadata" src="keyStage1.vtt" srclang="en" label="Key Stage 1">
    <track kind="metadata" src="keyStage2.vtt" srclang="en" label="Key Stage 2">
    <track kind="metadata" src="keyStage3.vtt" srclang="en" label="Key Stage 3">
</video>

my $tracks = $doc->querySelector('video')->textTracks;

# $tracks->length == 10
for( my $i = 0, $L = $tracks->length; $i < $L; $i++ )
{
    if( $tracks->[$i]->language eq 'en' )
    {
        say( $tracks->[$i] );
    }
}

Mozilla ref: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/textTracks

videoTracks 🎬

Read-only too. Same energy as above 🫶

Returns the list of VideoTrack objects contained in the element.

Mozilla ref: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/videoTracks

volume 🔊

It's a double indicating the audio volume, going from 0.0 (silent — the library voice) all the way to 1.0 (loudest — main character at the party) 🔥

Mozilla ref: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/volume

🎬 METHODS

Inherits methods from its parent HTML::Object::DOM::Element — yeah, it's that nepo-baby energy, but make it functional 💅

✨ addTextTrack

Okay so this one adds a text track (like, a track for subtitles ngl) to a media element. Iconic behaviour honestly.

It takes a track "kind", "label" and "language" and returns a brand new HTML::Object::DOM::TextTrack object 🎀

Possible values for "kind" are:

caption
chapters
descriptions
metadata
subtitles

"label" is a string specifying the label for the text track. It's used to identify the text track for the users 🫶

"language" in iso 639 format (e.g. en-US or ja-JP).

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/addTextTrack

✨ canPlayType

This always returns undef under perl. No cap, that's just how it is 😭

Normally, under JavaScript, given a string specifying a MIME media type (potentially with the codecs parameter included), canPlayType() returns the string probably if the media should be playable, maybe if there's not enough information to determine whether the media will play or not, or an empty string if the media cannot be played.

Example:

my $obj = $doc->createElement('video');
say( $obj->canPlayType('video/mp4') ); # "maybe"

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/canPlayType

✨ captureStream

This always returns undef under perl. Yep. Still cute though 💖

Normally, under JavaScript, this returns MediaStream, captures a stream of the media content.

Example:

$doc->querySelector('.playAndRecord')->addEventListener( click => sub
{
    my $playbackElement = $doc->getElementById("playback");
    my $captureStream = $playbackElement->captureStream();
    $playbackElement->play();
});

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/captureStream

✨ fastSeek

This always returns undef under perl. (Bestie the perl version is giving "I'm just here for the vibes" energy 🙈)

Normally, under JavaScript, this quickly seeks to the given time with low precision.

Example:

my $myVideo = $doc->getElementById("myVideoElement");

$myVideo->fastSeek(20);

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/fastSeek

✨ load

This always returns undef under perl.

Normally, under JavaScript, this resets the media to the beginning and selects the best available source from the sources provided using the src attribute or the <source> element.

Example:

my $mediaElem = $doc->querySelector("video");
$mediaElem->load();

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/load

✨ pause

Under perl, this does not do anything particular except setting the "paused" boolean value to true 🛑

Pauses the media playback.

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/pause

✨ play

This does not do anything in particular under perl, except setting the "paused" boolean value to false ▶️

Normally, under JavaScript, this begins playback of the media.

Example:

use Nice::Try;
my $videoElem = $doc->getElementById( 'video' );
my $playButton = $doc->getElementById( 'playbutton' );

$playButton->addEventListener( 'click', \&handlePlayButton, { capture => 0 });
playVideo();

sub playVideo
{
    try
    {
        $videoElem->play();
        $playButton->classList->add( 'playing' );
    }
    catch($err)
    {
        $playButton->classList->remove( 'playing' );
    }
}

sub handlePlayButton
{
    if( $videoElem->paused )
    {
        playVideo();
    }
    else
    {
        $videoElem->pause();
        $playButton->classList->remove( 'playing' );
    }
}

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/play

✨ removeTextTrack

You hand it a HTML::Object::DOM::TextTrack object and this will remove it. Bye bestie 👋

It returns the HTML::Object::DOM::TextTrack object upon success, or if it cannot be found, it returns undef

✨ seekToNextFrame

This always returns undef under perl.

Normally, under JavaScript, this seeks to the next frame in the media. This non-standard, experimental method makes it possible to manually drive reading and rendering of media at a custom speed, or to move through the media frame-by-frame to perform filtering or other operations. Very "film major with a custom rig" of it honestly 🎞️

✨ setMediaKeys

This always returns undef under perl.

Normally, under JavaScript, this returns Promise. Sets the MediaKeys keys to use when decrypting media during playback.

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/setMediaKeys

✨ setSinkId

This does not do anything particular under perl, except setting the value of "sinkid".

Normally, under JavaScript, this sets the ID of the audio device to use for output and returns a Promise. This only works when the application is authorized to use the specified device.

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/setSinkId

💫 EVENTS

🌸 abort

This is not used under perl, but you can trigger that event yourself. You're the main character, you can do whatever 💅

Under JavaScript, this is fired when the resource was not fully loaded, but not as the result of an error.

Example:

my $video = $doc->querySelector('video');
my $videoSrc = 'https://example.org/path/to/video.webm';

$video->addEventListener( abort => sub
{
    say( "Abort loading: ", $videoSrc );
});

my $source = $doc->createElement('source');
$source->setAttribute( src => $videoSrc );
$source->setAttribute( type => 'video/webm' );

$video->appendChild( $source );

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/abort_event

🌸 canplay

This is not used under perl, but you can trigger that event yourself.

Under JavaScript, this is fired when the user agent can play the media, but estimates that not enough data has been loaded to play the media up to its end without having to stop for further buffering of content

Example:

my $video = $doc->querySelector( 'video' );

$video->addEventListener( canplay => sub
{
    my $event = shift( @_ );
    say( 'Video can start, but not sure it will play through.' );
});

my $video = $doc->querySelector( 'video' );
$video->oncanplay = sub
{
    my $event = shift( @_ );
    say( 'Video can start, but not sure it will play through.' );
};

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/canplay_event

🌸 canplaythrough

This is not used under perl, but you can trigger that event yourself.

Under JavaScript, this is fired when the user agent can play the media, and estimates that enough data has been loaded to play the media up to its end without having to stop for further buffering of content.

Example:

my $video = $doc->querySelector( 'video' );

$video->addEventListener( canplaythrough => sub
{
    my $event = shift( @_ );
    say( "I think I can play through the entire video without ever having to stop to buffer." );
});

my $video = $doc->querySelector( 'video' );

$video->oncanplaythrough = sub
{
    my $event = shift( @_ );
    say( "I think I can play through the entire video without ever having to stop to buffer." );
};

🌸 durationchange

This is fired when the duration property has been updated. Like, the video got longer or shorter, who knows why 🤷‍♀️

Example:

my $video = $doc->querySelector('video');
$video->addEventListener( durationchange => sub
{
    say( 'Not sure why, but the duration of the $video has changed.' );
});

my $video = $doc->querySelector('video');

$video->ondurationchange = sub
{
    say( 'Not sure why, but the duration of the video has changed.' );
};

🌸 emptied

This is not used under perl, but you can trigger that event yourself.

Under JavaScript, this is fired when the media has become empty; for example, when the media has already been loaded (or partially loaded), and the load in HTML::Object::DOM::Element::Media method is called to reload it.

Example:

my $video = $doc->querySelector('video');

$video->addEventListener( emptied => sub
{
    say( 'Uh oh. The media is empty. Did you call load()?' );
});

my $video = $doc->querySelector('video');

$video->onemptied = sub
{
    say( 'Uh oh. The media is empty. Did you call load()?' );
};

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/emptied_event

🌸 ended

This is not used under perl, but you can trigger that event yourself.

Under JavaScript, this is fired when playback stops when end of the media (<audio> or <video>) is reached or because no further data is available.

Example:

my $obj = $doc->createElement('video');
say( $obj->ended ); # false

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/ended_event

🌸 error

Fired when the resource could not be loaded due to an error. Oop 💀

Example:

my $videoElement = $doc->createElement( 'video' );
$videoElement->onerror = sub
{
    say( "Error " . $videoElement->error->code . "; details: " . $videoElement->error->message );
}
$videoElement->src = "https://example.org/bogusvideo.mp4";

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/error_event

🌸 loadeddata

This is not used under perl, but you can trigger that event yourself.

Under JavaScript, this is fired when the first frame of the media has finished loading.

Example:

my $video = $doc->querySelector('video');

$video->addEventListener( loadeddata => sub
{
    say( 'Yay! The readyState just increased to HAVE_CURRENT_DATA or greater for the first time.' );
});

my $video = $doc->querySelector('video');

okay so finishing off loadeddata with the property-style handler:

$video->onloadeddata = sub
{
    say( 'Yay! The readyState just increased to HAVE_CURRENT_DATA or greater for the first time.' );
};

🎀 loadedmetadata

Heads up, bestie: this one is not used under perl, but you can trigger that event yourself. Under JavaScript, this is fired when the metadata has been loaded.

Example:

my $video = $doc->querySelector('video');

$video->addEventListener( loadedmetadata => sub
{
    say( 'The duration and dimensions of the media and tracks are now known.' );
});

my $video = $doc->querySelector('video');

$video->onloadedmetadata = sub
{
    say( 'The duration and dimensions of the media and tracks are now known.' );
};

💅 loadstart

Not used under perl — trigger it yourself if you want. Under JavaScript, this is fired when the browser has started to load a resource.

Example:

<div class="example">
    <button type="button">Load video</button>
    <video controls width="250"></video>

    <div class="event-log">
        <label>Event log:</label>
        <textarea readonly class="event-log-contents"></textarea>
    </div>
</div>

use feature 'signatures';
my $loadVideo = $doc->querySelector('button');
my $video = $doc->querySelector('video');
my $eventLog = $doc->querySelector('.event-log-contents');
my $source;

sub handleEvent( $event )
{
    $eventLog->textContent = $eventLog->textContent . $event->type . "\n";
}

$video->addEventListener( 'loadstart', \&handleEvent);
$video->addEventListener( 'progress', \&handleEvent);
$video->addEventListener( 'canplay', \&handleEvent);
$video->addEventListener( 'canplaythrough', \&handleEvent);

$loadVideo->addEventListener( click => sub
{
    if( $source )
    {
        $doc->location->reload();
    }
    else
    {
        $loadVideo->textContent = "Reset example";
        $source = $doc->createElement( 'source' );
        $source->setAttribute( 'src', 'https://example.org/some/where/media/examples/video.webm' );
        $source->setAttribute( 'type', 'video/webm' );
        $video->appendChild( $source );
    }
});

🦋 pause

Fired when a request to pause play is handled and the activity has entered its paused state, most commonly occurring when the media's pause in HTML::Object::DOM::Element::Media method is called.

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/pause_event

⭐ play

Fired when the paused property is changed from true to false, as a result of the play in HTML::Object::DOM::Element::Media method, or the autoplay attribute.

Example:

use Nice::Try; # for the try{}catch block
my $videoElem = $doc->getElementById( 'video' );
my $playButton = $doc->getElementById( 'playbutton' );

$playButton->addEventListener( click => \&handlePlayButton, { capture => 0 });
playVideo();

sub playVideo
{
    try {
        $videoElem->play();
        $playButton->classList->add( 'playing' );
    } catch( $err ) {
        $playButton->classList->remove( 'playing' );
    }
}

sub handlePlayButton
{
    if( $videoElem->paused )
    {
        playVideo();
    }
    else
    {
        $videoElem->pause();
        $playButton->classList->remove( 'playing' );
    }
}

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/play_event

🌸 playing

Not used under perl — you can trigger that event yourself, no cap. Under JavaScript, this is fired when playback is ready to start after having been paused or delayed due to lack of data.

Example:

my $video = $doc->querySelector('video');

$video->addEventListener( playing =>sub
{
    say( 'Video is no longer paused' );
});

my $video = $doc->querySelector('video');

$video->onplaying = sub
{
    say( 'Video is no longer paused.' );
};

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/playing_event

🍓 progress

Not used under perl, but you can trigger that event yourself. Under JavaScript, this is fired periodically as the browser loads a resource.

Example:

<div class="example">
    <button type="button">Load video</button>
    <video controls width="250"></video>

    <div class="event-log">
        <label>Event log:</label>
        <textarea readonly class="event-log-contents"></textarea>
    </div>
</div>

use feature 'signatures';
my $loadVideo = $doc->querySelector('button');
my $video = $doc->querySelector('video');
my $eventLog = $doc->querySelector('.event-log-contents');
my $source;

sub handleEvent( $event )
{
    $eventLog->textContent = $eventLog->textContent . $event->type . "\n";
}

$video->addEventListener( 'loadstart', \&handleEvent );
$video->addEventListener( 'progress', \&handleEvent );
$video->addEventListener( 'canplay', \&handleEvent );
$video->addEventListener( 'canplaythrough', \&handleEvent );

$loadVideo->addEventListener( click => sub
{
    if( $source )
    {
        $doc->location->reload();
    }
    else
    {
        $loadVideo->textContent = "Reset example";
        $source = $doc->createElement('source');
        $source->setAttribute( 'src', 'https://example.org/some/where/video.mp4' );
        $source->setAttribute( 'type', 'video/mp4' );
        $video->appendChild( $source );
    }
});

🧚 ratechange

This is fired when the playback rate has changed, i.e. when the property playbackRate is changed.

Example:

my $video = $doc->querySelector( 'video' );

$video->addEventListener( 'ratechange' => sub
{
    say( 'The playback rate changed.' );
});

my $video = $doc->querySelector('video');

$video->onratechange = sub
{
    say( 'The playback rate changed.' );
};

🔥 seeked

Not used under perl, but you can trigger that event yourself. Under JavaScript, this is fired when a seek operation completes.

Example:

my $video = $doc->querySelector('video');
$video->addEventListener( seeked => sub
{
    say( 'Video found the playback position it was looking for.' );
});
my $video = $doc->querySelector( 'video' );
$video->onseeked = sub
{
    say( 'Video found the playback position it was looking for.' );
};

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/seeked_event

🌈 seeking

Not used under perl — trigger it yourself if you need it. Under JavaScript, this is fired when a seek operation begins.

Example:

my $video = $doc->querySelector( 'video' );
$video->addEventListener( seeking => sub
{
    say( 'Video is seeking a new position.' );
});
my $video = $doc->querySelector( 'video' );
$video->onseeking = sub
{
    say( 'Video is seeking a new position.' );
};

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/seeking_event

💜 stalled

Not used under perl, but you can trigger that event yourself. Under JavaScript, this is fired when the user agent is trying to fetch media data, but data is unexpectedly not forthcoming.

Example:

my $video = $doc->querySelector('video');

$video->addEventListener( stalled => sub
{
    say( 'Failed to fetch data, but trying.' );
});

my $video = $doc->querySelector('video');

$video->onstalled = sub
{
    say( 'Failed to fetch data, but trying.' );
};

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/stalled_event

🫶 suspend

Not used under perl, bestie — trigger that event yourself if you want. Under JavaScript, this is fired when the media data loading has been suspended.

Example:

my $video = $doc->querySelector('video');

$video->addEventListener( suspend => sub
{
    say( 'Data loading has been suspended.' );
});

my $video = $doc->querySelector( 'video' );

$video->onsuspend = sub
{
    say( 'Data loading has been suspended.' );
};

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/suspend_event

🎬 timeupdate

Fired when the time indicated by the currentTime property has been updated.

Example:

my $video = $doc->querySelector('video');

$video->addEventListener( timeupdate => sub
{
    say( 'The currentTime attribute has been updated. Again.' );
});

my $video = $doc->querySelector('video');

$video->ontimeupdate = sub
{
    say( 'The currentTime attribute has been updated. Again.' );
};

👑 volumechange

Fired when the volume has changed, i.e. when the value for the volume property has changed.

Example:

my $video = $doc->querySelector('video');

$video->addEventListener( volumechange => sub
{
    say( 'The volume changed.' );
});

my $video = $doc->querySelector('video');
$video->onvolumechange = sub
{
    say( 'The volume changed.' );
};

Ok so wrapping up the events list 💫 — this one's basically "hey, the volume changed bestie":

That's a mood: Mozilla documentation literally right here: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/volumechange_event

waiting 🕐

Ok so heads up — this one is not used under perl, but you can trigger the event yourself whenever you feel like it. No cap, it's all you.

Under JavaScript tho, this fires when playback has stopped because of a temporary lack of data. Like the video is buffering and everyone's just staring at the spinner 😭

Example, and I'm giving it to you verbatim so nothing breaks:

my $video = $doc->querySelector('video');

$video->addEventListener( waiting => sub
{
    say( 'Video is waiting for more data.' );
});

my $video = $doc->querySelector('video');
$video->onwaiting = sub
{
    say( 'Video is waiting for more data.' );
};

Mozilla documentation for the receipts: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/waiting_event

✨ EVENT HANDLERS ✨

onencrypted 🔐

Sets the event handler that gets called when the media is encrypted. Spicy 🔥

Mozilla docs, go read: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/onencrypted

onwaitingforkey 🗝️

Sets the event handler called when playback is blocked while waiting for an encryption key. Literally just standing there waiting for the key bestie 💅

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/onwaitingforkey

🌈 CONSTANTS 🌈

These bad boys can be exported and used, like so:

use HTML::Object::DOM::Element::Media qw( :all );
# or directly from HTML::Object::DOM
use HTML::Object::DOM qw( :media );

NETWORK_EMPTY (0) — There's no data yet. Also, readyState is HAVE_NOTHING. Empty era, we've all been there 🙈
NETWORK_IDLE (1) — The media element is active and has selected a resource, but it is not using the network. Living off the grid, iconic 🦋
NETWORK_LOADING (2) — The browser is downloading HTML::Object::DOM::Element::Media data. Downloading era, main character energy ⭐
NETWORK_NO_SOURCE (3) — No HTML::Object::DOM::Element::Media src found 😭 The source is giving nothing, absolutely nothing.

👑 AUTHOR 👑

Jacques Deguest <jack@deguest.jp>

🫶 SEE ALSO 🫶

Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement
Mozilla documentation on audio element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio
Mozilla documentation on video element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video
W3C specifications: https://html.spec.whatwg.org/multipage/media.html

🎀 COPYRIGHT & LICENSE 🎀

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

And that's the whole page, bestie, you ate that 💅✨ Footer says perl v5.42.2, dated 2026-02-15, and this is HTML::O...t::Media(3) signing off 🍓 Go forth and slay your media elements 🧚💜

📦 where this page comes from

alpine 3.24: perl-html-object-doc 0.6.0-r1 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms