HTML::O...xtTrack(3)

📦 version 0.6.0, in alpine 3.24

💖 HTML::Object::DOM::TextTrack 💖

okay bestie, this is the User Contributed Perl Documentation manual page for HTML::O...xtTrack(3) — the HTML Object DOM Text Track Class. It's giving WebVTT main-character energy, no cap. 🦋

🎀 NAME 🎀

HTML::Object::DOM::TextTrack — HTML Object DOM Text Track Class.

✨ SYNOPSIS ✨

Here's the vibe in code form, literally:

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

<video controls>
    <source src="https://example.org/some/where/videos/video.webm" type="video/webm" />
    <source src="https://example.org/some/where/videos/video.mp4" type="video/mp4" />
    <track src="video-subtitles-en.vtt" label="English captions" kind="captions" srclang="en" default />
    <track src="video-subtitles-ja.vtt" label="日本語字幕" kind="captions" srclang="ja" />
    <p>This browser does not support the video element.</p>
</video>

🌸 VERSION 🌸

v0.2.0 — slay. 💅

🫶 DESCRIPTION 🫶

The TextTrack interface — part of the Web API for handling WebVTT (text tracks on media presentations) — describes and controls the text track associated with a particular <track> element (HTML::Object::DOM::Element::Track). ✨

Important vibe check: the TextTrack class is only a programmatic interface with no impact on the DOM. The track element is the one that accesses and modifies the DOM, and it makes use of this programmatic interface with TextTrack through its method track in HTML::Object::DOM::Element::Track.

This inherits from HTML::Object::DOM::MediaTrack. 🧚

👑 INHERITANCE 👑

The family tree is literally:

+-----------------------+     +---------------------------+     +-------------------------------+     +------------------------------+
| HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::MediaTrack | --> | HTML::Object::DOM::TextTrack |
+-----------------------+     +---------------------------+     +-------------------------------+     +------------------------------+

🎀 CONSTRUCTOR 🎀

new

new takes a track kind, label, and language, and returns a fresh 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 is in iso 639 format (e.g. en-US or ja-JP). See also rfc5646: https://datatracker.ietf.org/doc/html/rfc5646

💜 PROPERTIES 💜

Inherits properties from its parent HTML::Object::DOM::MediaTrack.

activeCues

Since there is no notion of "active cues" under the Perl environment, you can access the TextTrackCueList object this returns and add cues to it on your own. 🫶

Normally, under JavaScript, this returns a TextTrackCueList object listing the currently active set of text track cues. Track cues are active if the current playback position of the media is between the cues' start and end times. Thus, for displayed cues such as captions or subtitles, the active cues are currently being displayed.

Example:

my $video = $doc->querySelector('video');
my $track = $video->addTextTrack("captions", "Captions", "en");
$track->mode = 'showing';
say( $track->activeCues );

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

cues

Read-only. 🔒

A TextTrackCueList which contains all of the track's cues.

Example:

my $video = $doc->querySelector('video');
my $track = $video->addTextTrack('captions', 'Captions', 'en');
$track->mode = 'showing';
$track->addCue( HTML::Object::DOM::VTTCue->new(0, 0.9, 'Hildy!') );
$track->addCue( HTML::Object::DOM::VTTCue->new(1, 1.4, 'How are you?') );
say( $track->cues );

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

id

A string which identifies the track, if it has one. If it does not have an ID, then this value is an empty string (""). If the TextTrack is associated with a <track> element (HTML::Object::DOM::Element::Track), then the track's ID matches the element's ID.

Normally this should be read-only, but by design you can change it; only be careful if you do so. 👀

Example:

my $video = $doc->querySelector('video');
my $track = $video->addTextTrack("captions", "Captions", "en");
$track->mode = 'showing';
say( $track->id );

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

inBandMetadataTrackDispatchType

Returns a string which indicates the track's in-band metadata track dispatch type.

Example:

my $video = $doc->querySelector('video');
my $track = $video->addTextTrack("captions", "Captions", "en");
$track->mode = 'showing';
say( $track->inBandMetadataTrackDispatchType );

kind

Returns a string indicating what kind of text track the TextTrack describes. It must be one of the permitted values.

Normally this should be read-only, but by design you can change it; only be careful if you do so. 👀

Example:

my $video = $doc->querySelector('video');
my $track = $video->addTextTrack("captions", "Captions", "en");
$track->mode = 'showing';
say( $track->kind );

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

label

A human-readable string which contains the text track's label, if one is present; otherwise, this is an empty string (""), in which case a custom label may need to be generated by your code using other attributes of the track, if the track's label needs to be exposed to the user.

Normally this should be read-only, but by design you can change it; only be careful if you do so. 👀

Example:

my $video = $doc->querySelector('video');
my $track = $video->addTextTrack("captions", "Captions", "en");
$track->mode = 'showing';
say( $track->label );

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

language

A string which specifies the text language in which the text track's contents is written. The value must adhere to the format specified in RFC 5646: Tags for Identifying Languages (also known as BCP 47), just like the HTML lang attribute. For example, this can be en-US for United States English or pt-BR for Brazilian Portuguese.

Normally this should be read-only, but by design you can change it; only be careful if you do so. 👀

Example:

my $video = $doc->querySelector('video');
my $track = $video->addTextTrack("captions", "Captions", "en-US");
$track->mode = 'showing';
say( $track->language ); # en-US

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

mode

A string specifying the track's current mode, which must be one of the permitted values. Changing this property's value changes the track's current mode to match. The default is disabled, unless the <track> element's default boolean attribute is specified, in which case the default mode is started.

Possible values are: disabled, hidden, showing, but you are free to use whatever you want of course.

Example:

$doc->addEventListener( load => sub
{
    my $trackElem = $doc->querySelector("track");
    my $track = $trackElem->track;

    $track->mode = 'showing';

    for( my $index = 0; index < $track->cues->length; index++ )
    {
        my $cue = $track->cues->[ $index ];
        $cue->pauseOnExit = 1; # true
    };
});

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

🔥 METHODS 🔥

Inherits methods from its parent HTML::Object::DOM::MediaTrack.

addCue

Adds a cue (specified as a TextTrackCue object) to the track's list of cues.

When doing so, this will set the TextTrackCue object's track property to this object, and will also check it is not already added to avoid duplicates.

It returns the current TextTrack object upon success or upon error it returns undef and sets an error.

Example:

my $video = $doc->querySelector('video');
my $track = $video->addTextTrack("captions", "Captions", "en");
$track->mode = 'showing';
$track->addCue( HTML::Object::DOM::VTTCue->new(0, 0.9, 'Hildy!') );
$track->addCue( HTML::Object::DOM::VTTCue->new(1, 1.4, 'How are you?') );

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

removeCue

Removes a cue (specified as a TextTrackCue object) from the track's list of cues.

When doing so, this checks the object provided does exist among our cues or it returns undef if it does not exist.

If found, it removes it from our cues and unsets the cue's track property.

It returns the removed TextTrackCue object upon success or upon error it returns undef and sets an error.

Example:

my $video = $doc->querySelector('video');
my $track = $video->addTextTrack("captions", "Captions", "en");
$track->mode = 'showing';
my $cue = HTML::Object::DOM::VTTCue->new(0, 0.9, 'Hildy!');
$track->addCue( $cue );
$track->removeCue( $cue );

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

💌 AUTHOR 💌

Jacques Deguest <jack@deguest.jp>

🌈 SEE ALSO 🌈

Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/TextTrack
VideoJS documentation: https://docs.videojs.com/tutorial-text-tracks.html
rfc5646 for language codes: https://datatracker.ietf.org/doc/html/rfc5646>
W3C specificiations: https://html.spec.whatwg.org/multipage/media.html#texttrack

🍓 COPYRIGHT & LICENSE 🍓

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

okay that's the whole page, bestie 💅 Signed off with source/version perl v5.42.2, dated 2026-02-15, for HTML::O...xtTrack(3). Byeee 🦋✨

📦 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