The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
HTML-Object-v0.2.0
River stage zero No dependents
1 ++
/ HTML::Object::DOM::TextTrack

NAME

HTML::Object::DOM::TextTrack - HTML Object DOM Text Track Class

SYNOPSIS

    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

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>.

TextTrack class is only a programmatic interface with no impact on the DOM whereas track element accesses and modifies the DOM and 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

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

CONSTRUCTOR

new

This takes a track kind, label and language and this returns a 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. Is used to identify the text track for the users.

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

PROPERTIES

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

activeCues

Since there is no notion of 'active cues' under 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

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

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

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 );

See also Mozilla documentation

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

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

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

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 your 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

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 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

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 exists among our cues or it returns undef if it does not exist.

If found, it removes it from our cues, unset 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

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Mozilla documentation, VideoJS documentation, rfc5646 for language codes>, W3C specificiations

COPYRIGHT & LICENSE

Copyright(c) 2021 DEGUEST Pte. Ltd.

All rights reserved

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