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.5.0
River stage one • 1 direct dependent • 2 total dependents
1 ++
/ HTML::Object::DOM::VTTCue

NAME

HTML::Object::DOM::VTTCue - HTML Object DOM VTTCue Class

SYNOPSIS

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

    <video controls src="https://example.org/some/where/media/video.mp4"></video>

    my $video = $doc->querySelector('video');
    my $track = $video->addTextTrack("captions", "Captions", "en");
    $track->mode = 'showing';
    $track->addCue( new HTML::Object::DOM::VTTCue( 0, 0.9, 'Hildy!') ) ;
    $track->addCue( new HTML::Object::DOM::VTTCue( 1, 1.4, 'How are you?' ) );
    $track->addCue( new HTML::Object::DOM::VTTCue( 1.5, 2.9, 'Tell me, is the lord of the universe in?' ) );
    $track->addCue( new HTML::Object::DOM::VTTCue( 3, 4.2, 'Yes, he\'s in - in a bad humor' ) );
    $track->addCue( new HTML::Object::DOM::VTTCue( 4.3, 6, 'Somebody must\'ve stolen the crown jewels' ) );
    say( $track->cues );

VERSION

    v0.2.0

DESCRIPTION

This implements a VTTCue object representing a cue which will be presented during the time span given.

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

INHERITANCE

    +---------------------------------+     +---------------------------+
    | HTML::Object::DOM::TextTrackCue | --> | HTML::Object::DOM::VTTCue |
    +---------------------------------+     +---------------------------+

CONSTRUCTOR

new

VTTCue takes 3 parameters: startTime, endTime and text

startTime

This is a double representing the initial text track cue start time. This is the time, given in seconds and fractions of a second, denoting the beginning of the range of the media data to which this cue applies. For example, if a cue is to be visible from 50 seconds to a one minute, five and a half seconds in the media's playback, startTime will be 50.0. endTime

endTime

This is a double representing the ending time for this text track cue. This is the time at which the cue should stop being presented to the user, given in seconds and fractions thereof. Given the example cue mentioned under startTime, the value of endTime would be 65.5. text

text

A string providing the text that will be shown during the time span indicated by startTime and endTime.

PROPERTIES

align

Returns an enum representing the alignment of all the lines of text within the cue box.

Example:

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

    my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
    $cue1->align = 'start';
    say( $cue1->align );

    $track->addCue( $cue1 );

See also Mozilla documentation

endTime

This is a double representing the ending time for this text track cue. This is the time at which the cue should stop being presented to the user, given in seconds and fractions thereof. Given the example cue mentioned under startTime, the value of endTime would be 65.5. text

line

Returns the line positioning of the cue. This can be the string auto or a number whose interpretation depends on the value of "snapToLines".

Example:

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

    my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
    $cue1->line = '1';
    say( $cue1->line );

    $track->addCue( $cue1 );

See also Mozilla documentation

lineAlign

Returns an enum representing the alignment of the "line".

Example:

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

    my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
    $cue1->lineAlign = 'center';
    say( $cue1->lineAlign );

    $track->addCue( $cue1 );

See also Mozilla documentation

position

Returns the indentation of the cue within the line. This can be the string auto or a number representing the percentage of the "region", or the video size if "region" is undef.

Example:

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

    my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
    $cue1->position = '2';
    say( $cue1->position );

    $track->addCue( $cue1 );

See also Mozilla documentation

positionAlign

Returns an enum representing the alignment of the cue. This is used to determine what the "position" is anchored to. The default is auto.

Example:

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

    my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
    $cue1->positionAlign = 'line-right';
    say( $cue1->positionAlign );

    $track->addCue( $cue1 );

See also Mozilla documentation

region

A VTTRegion object describing the video's sub-region that the cue will be drawn onto, or undef if none is assigned.

Example:

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

    my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
    say( $cue1->region );

    $track->addCue( $cue1 );

See also Mozilla documentation

size

Returns a double representing the size of the cue, as a percentage of the video size.

Example:

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

    my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
    $cue1->size = 50;
    say( $cue1->size );

    $track->addCue( $cue1 );

See also Mozilla documentation

snapToLines

Returns true if the "line" attribute is an integer number of lines or a percentage of the video size.

Example:

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

    my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
    $cue1->snapToLines = 1; # true
    say( $cue1->snapToLines );

    $track->addCue( $cue1 );

See also Mozilla documentation

startTime

This is a double representing the initial text track cue start time. This is the time, given in seconds and fractions of a second, denoting the beginning of the range of the media data to which this cue applies. For example, if a cue is to be visible from 50 seconds to a one minute, five and a half seconds in the media's playback, startTime will be 50.0. endTime

text

Returns a string with the contents of the cue.

Example:

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

    my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
    $cue1->text = 'new cue value';
    say( $cue1->text ) # 'new cue value';

    $track->addCue( $cue1 );

See also Mozilla documentation

vertical

Returns an enum representing the cue writing direction.

Example:

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

    my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
    $cue1->vertical = 'rl';
    say( $cue1->vertical );

    $track->addCue( $cue1 );

See also Mozilla documentation

METHODS

Inherits methods from its parent HTML::Object::Element

getCueAsHTML

Returns the cue text as a HTML::Object::DOM::DocumentFragment.

Example:

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

    my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
    say( $cue1->getCueAsHTML() );

    $track->addCue( $cue1 );

See also Mozilla documentation

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Mozilla documentation, W3C specifications, Specifications

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.