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