File Coverage

lib/HTML/Object/DOM/TextTrack.pm
Criterion Covered Total %
statement 22 60 36.6
branch 0 14 0.0
condition 0 4 0.0
subroutine 8 15 53.3
pod 7 7 100.0
total 37 100 37.0


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## HTML Object - ~/lib/HTML/Object/DOM/TextTrack.pm
3             ## Version v0.2.0
4             ## Copyright(c) 2021 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <jack@deguest.jp>
6             ## Created 2021/12/27
7             ## Modified 2022/09/18
8             ## All rights reserved
9             ##
10             ##
11             ## This program is free software; you can redistribute it and/or modify it
12             ## under the same terms as Perl itself.
13             ##----------------------------------------------------------------------------
14             package HTML::Object::DOM::TextTrack;
15             BEGIN
16             {
17 1     1   2746 use strict;
  1         2  
  1         34  
18 1     1   5 use warnings;
  1         1  
  1         29  
19 1     1   5 use parent qw( HTML::Object::DOM::MediaTrack );
  1         2  
  1         5  
20 1     1   103 use vars qw( $VERSION );
  1         2  
  1         39  
21 1     1   5 use HTML::Object::Exception;
  1         5  
  1         9  
22 1     1   293 our $VERSION = 'v0.2.0';
23             };
24              
25 1     1   6 use strict;
  1         1  
  1         40  
26 1     1   8 use warnings;
  1         2  
  1         595  
27              
28             sub init
29             {
30 0     0 1   my $self = shift( @_ );
31 0 0         return( $self->error({
32             message => sprintf( "At least 1 argument required, but only %d passed", scalar( @_ ) ),
33             class => 'HML::Object::TypeError',
34             }) ) if( scalar( @_ ) < 3 );
35 0           my $kind = shift( @_ );
36 0           my $label = shift( @_ );
37 0           my $lang = shift( @_ );
38 0 0         return( $self->error({
39             message => "kind argument provided is not a string",
40             class => 'HML::Object::TypeError',
41             }) ) if( $kind !~ /^\w+$/ );
42 0           $self->{cues} = [];
43             # If set, this should be the same as the id in HTML::Object::DOM::Element::Track
44 0           $self->{id} = undef;
45 0           $self->{kind} = $kind;
46 0           $self->{label} = $label;
47 0           $self->{language} = $lang;
48 0           $self->{mode} = 'hidden';
49 0           $self->{_init_strict_use_sub} = 1;
50 0 0         $self->SUPER::init( @_ ) || return( $self->pass_error );
51 0           return( $self );
52             }
53              
54             # Note: property
55 0     0 1   sub activeCues { return( shift->_set_get_object( 'activecues', 'HTML::Object::DOM::TextTrackCueList', @_ ) ); }
56              
57             sub addCue
58             {
59 0     0 1   my $self = shift( @_ );
60 0   0       my $cue = shift( @_ ) || return( $self->error({
61             message => "No cue object was provided.",
62             class => 'HTML::Object::TypeError',
63             }) );
64             # HTML::Object::DOM::VTTCue inherits from HTML::Object::DOM::TextTrackCue
65 0 0         return( $self->error({
66             message => "Cue provided is not a HTML::Object::DOM::TextTrackCue object.",
67             class => 'HTML::Object::TypeError',
68             }) ) if( !$self->_is_a( $cue => 'HTML::Object::DOM::TextTrackCue' ) );
69 0           my $cues = $self->cues;
70 0           my $pos = $cues->pos( $cue );
71 0 0         if( !defined( $cue ) )
72             {
73 0           $cue->track( $self );
74 0           $cues->push( $cue );
75             }
76 0           return( $self );
77             }
78              
79             # Note: property
80 0     0 1   sub cues { return( shift->_set_get_object_array_object( 'cues', 'HTML::Object::DOM::TextTrackCueList', @_ ) ); }
81              
82             # Note: property id inherited
83              
84             # Note: property
85 0     0 1   sub inBandMetadataTrackDispatchType : lvalue { return( shift->_set_get_scalar_as_object( 'inbandmetadatatrackdispatchtype', @_ ) ); }
86              
87             # Note: property kind inherited
88              
89             # Note: property label inherited
90              
91             # Note: property language inherited
92              
93             # Note: property
94 0     0 1   sub mode : lvalue { return( shift->_set_get_scalar_as_object( 'mode', @_ ) ); }
95              
96             # Note: method parent is used and inherited from HTML::Object::Element via HTML::Object::EventTarget
97              
98             sub removeCue
99             {
100 0     0 1   my $self = shift( @_ );
101 0   0       my $cue = shift( @_ ) || return( $self->error({
102             message => "No cue object was provided.",
103             class => 'HTML::Object::TypeError',
104             }) );
105 0 0         return( $self->error({
106             message => "Cue provided is not a HTML::Object::DOM::TextTrackCue object.",
107             class => 'HTML::Object::TypeError',
108             }) ) if( !$self->_is_a( $cue => 'HTML::Object::DOM::TextTrackCue' ) );
109 0           my $cues = $self->cues;
110 0           my $pos = $cues->pos( $cue );
111 0 0         if( defined( $pos ) )
112             {
113 0           $cues->splice( $pos, 1 );
114 0           $cue->track( undef );
115 0           return( $cue );
116             }
117 0           return;
118             }
119              
120             1;
121             # NOTE: POD
122             __END__
123              
124             =encoding utf-8
125              
126             =head1 NAME
127              
128             HTML::Object::DOM::TextTrack - HTML Object DOM Text Track Class
129              
130             =head1 SYNOPSIS
131              
132             use HTML::Object::DOM::TextTrack;
133             my $track = HTML::Object::DOM::TextTrack->new ||
134             die( HTML::Object::DOM::TextTrack->error, "\n" );
135              
136             <video controls>
137             <source src="https://example.org/some/where/videos/video.webm" type="video/webm" />
138             <source src="https://example.org/some/where/videos/video.mp4" type="video/mp4" />
139             <track src="video-subtitles-en.vtt" label="English captions" kind="captions" srclang="en" default />
140             <track src="video-subtitles-ja.vtt" label="日本語字幕" kind="captions" srclang="ja" />
141             <p>This browser does not support the video element.</p>
142             </video>
143              
144             =head1 VERSION
145              
146             v0.2.0
147              
148             =head1 DESCRIPTION
149              
150             The C<TextTrack> interface—part of the Web API for handling C<WebVTT> (text tracks on media presentations)—describes and controls the text track associated with a particular L<<track> element|HTML::Object::DOM::Element::Track>.
151              
152             C<TextTrack> class is only a programmatic interface with no impact on the DOM whereas L<track element|HTML::Object::DOM::Element::Track> accesses and modifies the DOM and makes use of this programmatic interface with C<TextTrack> through its method L<HTML::Object::DOM::Element::Track/track>
153              
154             This inherits from L<HTML::Object::DOM::MediaTrack>
155              
156             =head1 INHERITANCE
157              
158             +-----------------------+ +---------------------------+ +-------------------------------+ +------------------------------+
159             | HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::MediaTrack | --> | HTML::Object::DOM::TextTrack |
160             +-----------------------+ +---------------------------+ +-------------------------------+ +------------------------------+
161              
162             =head1 CONSTRUCTOR
163              
164             =head2 new
165              
166             This takes a track C<kind>, C<label> and C<language> and this returns a new C<HTML::Object::DOM::TextTrack> object.
167              
168             Possible values for C<kind> are:
169              
170             =over 4
171              
172             =item caption
173              
174             =item chapters
175              
176             =item descriptions
177              
178             =item metadata
179              
180             =item subtitles
181              
182             =back
183              
184             C<label> is a string specifying the label for the text track. Is used to identify the text track for the users.
185              
186             C<language> in iso 639 format (e.g. C<en-US> or C<ja-JP>). Seel also L<rfc5646|https://datatracker.ietf.org/doc/html/rfc5646>
187              
188             =head1 PROPERTIES
189              
190             Inherits properties from its parent L<HTML::Object::DOM::MediaTrack>
191              
192             =head2 activeCues
193              
194             Since there is no notion of 'active cues' under perl environment, you can access the L<TextTrackCueList object|HTML::Object::DOM::TextTrackCueList> this returns and add cues to it on your own.
195              
196             Normally, under JavaScript, this returns a L<TextTrackCueList|HTML::Object::DOM::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.
197              
198             Example:
199              
200             my $video = $doc->querySelector('video');
201             my $track = $video->addTextTrack("captions", "Captions", "en");
202             $track->mode = 'showing';
203             say( $track->activeCues );
204              
205             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/activeCues>
206              
207             =head2 cues
208              
209             Read-only.
210              
211             A L<TextTrackCueList|HTML::Object::DOM::TextTrackCueList> which contains all of the track's cues.
212              
213             Example:
214              
215             my $video = $doc->querySelector('video');
216             my $track = $video->addTextTrack('captions', 'Captions', 'en');
217             $track->mode = 'showing';
218             $track->addCue( HTML::Object::DOM::VTTCue->new(0, 0.9, 'Hildy!') );
219             $track->addCue( HTML::Object::DOM::VTTCue->new(1, 1.4, 'How are you?') );
220             say( $track->cues );
221              
222             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/cues>
223              
224             =head2 id
225              
226             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 C<TextTrack> is associated with a L<<track> element|HTML::Object::DOM::Element::Track>, then the track's ID matches the element's ID.
227              
228             Normally this should be read-only, but by design you can change it; only be careful if you do so.
229              
230             Example:
231              
232             my $video = $doc->querySelector('video');
233             my $track = $video->addTextTrack("captions", "Captions", "en");
234             $track->mode = 'showing';
235             say( $track->id );
236              
237             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/id>
238              
239             =head2 inBandMetadataTrackDispatchType
240              
241             Returns a string which indicates the track's in-band metadata track dispatch type.
242              
243             Example:
244              
245             my $video = $doc->querySelector('video');
246             my $track = $video->addTextTrack("captions", "Captions", "en");
247             $track->mode = 'showing';
248             say( $track->inBandMetadataTrackDispatchType );
249              
250             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/inBandMetadataTrackDispatchType>
251              
252             =head2 kind
253              
254             Returns a string indicating what kind of text track the C<TextTrack> describes. It must be one of the permitted values.
255              
256             Normally this should be read-only, but by design you can change it; only be careful if you do so.
257              
258             Example:
259              
260             my $video = $doc->querySelector('video');
261             my $track = $video->addTextTrack("captions", "Captions", "en");
262             $track->mode = 'showing';
263             say( $track->kind );
264              
265             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/kind>
266              
267             =head2 label
268              
269             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.
270              
271             Normally this should be read-only, but by design you can change it; only be careful if you do so.
272              
273             Example:
274              
275             my $video = $doc->querySelector('video');
276             my $track = $video->addTextTrack("captions", "Captions", "en");
277             $track->mode = 'showing';
278             say( $track->label );
279              
280             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/label>
281              
282             =head2 language
283              
284             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.
285              
286             Normally this should be read-only, but by design you can change it; only be careful if you do so.
287              
288             Example:
289              
290             my $video = $doc->querySelector('video');
291             my $track = $video->addTextTrack("captions", "Captions", "en-US");
292             $track->mode = 'showing';
293             say( $track->language ); # en-US
294              
295             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/language>
296              
297             =head2 mode
298              
299             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 C<disabled>, unless the C<<track>> element's default boolean attribute is specified, in which case the default mode is C<started>.
300              
301             Possible values are: C<disabled>, C<hidden>, C<showing>, but you are free to use whatever your want of course.
302              
303             Example:
304              
305             $doc->addEventListener( load => sub
306             {
307             my $trackElem = $doc->querySelector("track");
308             my $track = $trackElem->track;
309              
310             $track->mode = 'showing';
311              
312             for( my $index = 0; index < $track->cues->length; index++ )
313             {
314             my $cue = $track->cues->[ $index ];
315             $cue->pauseOnExit = 1; # true
316             };
317             });
318              
319             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/mode>
320              
321             =head1 METHODS
322              
323             Inherits methods from its parent L<HTML::Object::DOM::MediaTrack>
324              
325             =head2 addCue
326              
327             Adds a cue (specified as a L<TextTrackCue object|HTML::Object::DOM::TextTrackCue>) to the track's list of cues.
328              
329             When doing so, this will set the L<TextTrackCue object|HTML::Object::DOM::TextTrackCue> C<track> property to this object, and will also check it is not already added to avoid duplicates.
330              
331             It returns the current C<TextTrack> object upon success or upon error it returns C<undef> and sets an L<error|Module::Generic/error>
332              
333             Example:
334              
335             my $video = $doc->querySelector('video');
336             my $track = $video->addTextTrack("captions", "Captions", "en");
337             $track->mode = 'showing';
338             $track->addCue( HTML::Object::DOM::VTTCue->new(0, 0.9, 'Hildy!') );
339             $track->addCue( HTML::Object::DOM::VTTCue->new(1, 1.4, 'How are you?') );
340              
341             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/addCue>
342              
343             =head2 removeCue
344              
345             Removes a cue (specified as a L<TextTrackCue object|HTML::Object::DOM::TextTrackCue>) from the track's list of cues.
346              
347             When doing so, this checks the object provided does exists among our cues or it returns C<undef> if it does not exist.
348              
349             If found, it removes it from our cues, unset the cue's C<track> property.
350              
351             It returns the removed C<TextTrackCue> object upon success or upon error it returns C<undef> and sets an L<error|Module::Generic/error>
352              
353             Example:
354              
355             my $video = $doc->querySelector('video');
356             my $track = $video->addTextTrack("captions", "Captions", "en");
357             $track->mode = 'showing';
358             my $cue = HTML::Object::DOM::VTTCue->new(0, 0.9, 'Hildy!');
359             $track->addCue( $cue );
360             $track->removeCue( $cue );
361              
362             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/removeCue>
363              
364             =head1 AUTHOR
365              
366             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
367              
368             =head1 SEE ALSO
369              
370             L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrack>, L<VideoJS documentation|https://docs.videojs.com/tutorial-text-tracks.html>, L<rfc5646 for language codes|https://datatracker.ietf.org/doc/html/rfc5646>>, L<W3C specificiations|https://html.spec.whatwg.org/multipage/media.html#texttrack>
371              
372             =head1 COPYRIGHT & LICENSE
373              
374             Copyright(c) 2021 DEGUEST Pte. Ltd.
375              
376             All rights reserved
377              
378             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
379              
380             =cut