File Coverage

lib/HTML/Object/DOM/VTTCue.pm
Criterion Covered Total %
statement 22 54 40.7
branch 0 10 0.0
condition 0 2 0.0
subroutine 8 22 36.3
pod 14 14 100.0
total 44 102 43.1


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## HTML Object - ~/lib/HTML/Object/DOM/VTTCue.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::VTTCue;
15             BEGIN
16             {
17 1     1   1057 use strict;
  1         4  
  1         32  
18 1     1   7 use warnings;
  1         2  
  1         29  
19 1     1   6 use parent qw( HTML::Object::DOM::TextTrackCue );
  1         4  
  1         4  
20 1     1   72 use vars qw( $VERSION );
  1         2  
  1         40  
21 1     1   6 use HTML::Object::Exception;
  1         2  
  1         10  
22 1     1   315 our $VERSION = 'v0.2.0';
23             };
24              
25 1     1   10 use strict;
  1         2  
  1         23  
26 1     1   5 use warnings;
  1         3  
  1         657  
27              
28             sub init
29             {
30 0     0 1   my $self = shift( @_ );
31 0 0         return( $self->error({
32             message => sprintf( "At least 3 arguments required, but only %d passed", scalar( @_ ) ),
33             class => 'HML::Object::TypeError',
34             }) ) if( scalar( @_ ) < 3 );
35 0           my $start = shift( @_ );
36 0           my $end = shift( @_ );
37 0           my $text = shift( @_ );
38 0 0         return( $self->error({
39             message => "start argument provided is not a number",
40             class => 'HML::Object::TypeError',
41             }) ) if( !$self->_is_number( $start ) );
42 0 0         return( $self->error({
43             message => "end argument provided is not a number",
44             class => 'HML::Object::TypeError',
45             }) ) if( !$self->_is_number( $end ) );
46 0           $self->{positionalign} = 'auto';
47 0           $self->{startTime} = $start;
48 0           $self->{endTime} = $end;
49 0           $self->{text} = $text;
50 0           $self->{_init_strict_use_sub} = 1;
51 0 0         $self->SUPER::init( @_ ) || return( $self->pass_error );
52 0           return( $self );
53             }
54              
55             # Note: property
56 0     0 1   sub align : lvalue { return( shift->_set_get_scalar_as_object( 'align', @_ ) ); }
57              
58 0     0 1   sub endTime : lvalue { return( shift->_set_get_scalar_as_object( 'endTime', @_ ) ); }
59              
60             sub getCueAsHTML
61             {
62 0     0 1   my $self = shift( @_ );
63 0 0         $self->_load_class( 'HTML::Object::DOM::DocumentFragment' ) || return( $self->pass_error );
64 0           my $frag = HTML::Object::DOM::DocumentFragment->new;
65 0   0       my $text = $frag->new_text( value => $self->{text} ) || return( $self->pass_error( $frag->error ) );
66 0           $frag->appendChild( $text );
67 0           return( $frag );
68             }
69              
70             # Note: property
71 0     0 1   sub line : lvalue { return( shift->_set_get_scalar_as_object( 'line', @_ ) ); }
72              
73             # Note: property
74 0     0 1   sub lineAlign : lvalue { return( shift->_set_get_scalar_as_object( 'linealign', @_ ) ); }
75              
76             # Note: property
77 0     0 1   sub position : lvalue { return( shift->_set_get_scalar_as_object( 'position', @_ ) ); }
78              
79             # Note: property
80 0     0 1   sub positionAlign : lvalue { return( shift->_set_get_scalar_as_object( 'positionalign', @_ ) ); }
81              
82             # Note: property
83 0     0 1   sub region : lvalue { return( shift->_set_get_object_without_init( 'region', 'HTML::Object::DOM::VTTRegion', @_ ) ); }
84              
85             # Note: property
86 0     0 1   sub size : lvalue { return( shift->_set_get_number( 'size', @_ ) ); }
87              
88             # Note: property
89 0     0 1   sub snapToLines : lvalue { return( shift->_set_get_boolean( 'snaptolines', @_ ) ); }
90              
91 0     0 1   sub startTime : lvalue { return( shift->_set_get_scalar_as_object( 'startTime', @_ ) ); }
92              
93             # Note: property
94 0     0 1   sub text : lvalue { return( shift->_set_get_scalar_as_object( 'text', @_ ) ); }
95              
96             # Note: property
97 0     0 1   sub vertical : lvalue { return( shift->_set_get_scalar_as_object( 'vertical', @_ ) ); }
98              
99             1;
100             # NOTE: POD
101             __END__
102              
103             =encoding utf-8
104              
105             =head1 NAME
106              
107             HTML::Object::DOM::VTTCue - HTML Object DOM VTTCue Class
108              
109             =head1 SYNOPSIS
110              
111             use HTML::Object::DOM::VTTCue;
112             my $cue = HTML::Object::DOM::VTTCue->new ||
113             die( HTML::Object::DOM::VTTCue->error, "\n" );
114              
115             <video controls src="https://example.org/some/where/media/video.mp4"></video>
116              
117             my $video = $doc->querySelector('video');
118             my $track = $video->addTextTrack("captions", "Captions", "en");
119             $track->mode = 'showing';
120             $track->addCue( new HTML::Object::DOM::VTTCue( 0, 0.9, 'Hildy!') ) ;
121             $track->addCue( new HTML::Object::DOM::VTTCue( 1, 1.4, 'How are you?' ) );
122             $track->addCue( new HTML::Object::DOM::VTTCue( 1.5, 2.9, 'Tell me, is the lord of the universe in?' ) );
123             $track->addCue( new HTML::Object::DOM::VTTCue( 3, 4.2, 'Yes, he\'s in - in a bad humor' ) );
124             $track->addCue( new HTML::Object::DOM::VTTCue( 4.3, 6, 'Somebody must\'ve stolen the crown jewels' ) );
125             say( $track->cues );
126              
127             =head1 VERSION
128              
129             v0.2.0
130              
131             =head1 DESCRIPTION
132              
133             This implements a C<VTTCue> object representing a cue which will be presented during the time span given.
134              
135             The C<VTTCue> 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>.
136              
137             =head1 INHERITANCE
138              
139             +---------------------------------+ +---------------------------+
140             | HTML::Object::DOM::TextTrackCue | --> | HTML::Object::DOM::VTTCue |
141             +---------------------------------+ +---------------------------+
142              
143             =head1 CONSTRUCTOR
144              
145             =head2 new
146              
147             C<VTTCue> takes 3 parameters: C<startTime>, C<endTime> and C<text>
148              
149             =over 4
150              
151             =item startTime
152              
153             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, C<startTime> will be 50.0.
154             C<endTime>
155              
156             =item endTime
157              
158             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 C<startTime>, the value of C<endTime> would be 65.5.
159             text
160              
161             =item text
162              
163             A string providing the text that will be shown during the time span indicated by C<startTime> and C<endTime>.
164              
165             =back
166              
167             =head1 PROPERTIES
168              
169             =head2 align
170              
171             Returns an enum representing the alignment of all the lines of text within the cue box.
172              
173             Example:
174              
175             my $video = $doc->querySelector('video');
176             my $track = $video->addTextTrack("captions", "Captions", "en");
177             $track->mode = "showing";
178              
179             my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
180             $cue1->align = 'start';
181             say( $cue1->align );
182              
183             $track->addCue( $cue1 );
184              
185             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VTTCue/align>
186              
187             =head2 endTime
188              
189             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 C<startTime>, the value of C<endTime> would be 65.5.
190             text
191              
192             =head2 line
193              
194             Returns the line positioning of the cue. This can be the string C<auto> or a number whose interpretation depends on the value of L</snapToLines>.
195              
196             Example:
197              
198             my $video = $doc->querySelector('video');
199             my $track = $video->addTextTrack("captions", "Captions", "en");
200             $track->mode = "showing";
201              
202             my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
203             $cue1->line = '1';
204             say( $cue1->line );
205              
206             $track->addCue( $cue1 );
207              
208             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VTTCue/line>
209              
210             =head2 lineAlign
211              
212             Returns an enum representing the alignment of the L</line>.
213              
214             Example:
215              
216             my $video = $doc->querySelector('video');
217             my $track = $video->addTextTrack("captions", "Captions", "en");
218             $track->mode = "showing";
219              
220             my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
221             $cue1->lineAlign = 'center';
222             say( $cue1->lineAlign );
223              
224             $track->addCue( $cue1 );
225              
226             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VTTCue/lineAlign>
227              
228             =head2 position
229              
230             Returns the indentation of the cue within the line. This can be the string C<auto> or a number representing the percentage of the L</region>, or the video size if L</region> is C<undef>.
231              
232             Example:
233              
234             my $video = $doc->querySelector('video');
235             my $track = $video->addTextTrack("captions", "Captions", "en");
236             $track->mode = "showing";
237              
238             my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
239             $cue1->position = '2';
240             say( $cue1->position );
241              
242             $track->addCue( $cue1 );
243              
244             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VTTCue/position>
245              
246             =head2 positionAlign
247              
248             Returns an enum representing the alignment of the cue. This is used to determine what the L</position> is anchored to. The default is C<auto>.
249              
250             Example:
251              
252             my $video = $doc->querySelector('video');
253             my $track = $video->addTextTrack("captions", "Captions", "en");
254             $track->mode = "showing";
255              
256             my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
257             $cue1->positionAlign = 'line-right';
258             say( $cue1->positionAlign );
259              
260             $track->addCue( $cue1 );
261              
262             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VTTCue/positionAlign>
263              
264             =head2 region
265              
266             A L<VTTRegion|HTML::Object::DOM::VTTRegion> object describing the video's sub-region that the cue will be drawn onto, or C<undef> if none is assigned.
267              
268             Example:
269              
270             my $video = $doc->querySelector('video');
271             my $track = $video->addTextTrack("captions", "Captions", "en");
272             $track->mode = "showing";
273              
274             my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
275             say( $cue1->region );
276              
277             $track->addCue( $cue1 );
278              
279             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VTTCue/region>
280              
281             =head2 size
282              
283             Returns a double representing the size of the cue, as a percentage of the video size.
284              
285             Example:
286              
287             my $video = $doc->querySelector('video');
288             my $track = $video->addTextTrack("captions", "Captions", "en");
289             $track->mode = "showing";
290              
291             my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
292             $cue1->size = 50;
293             say( $cue1->size );
294              
295             $track->addCue( $cue1 );
296              
297             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VTTCue/size>
298              
299             =head2 snapToLines
300              
301             Returns true if the L</line> attribute is an integer number of lines or a percentage of the video size.
302              
303             Example:
304              
305             my $video = $doc->querySelector('video');
306             my $track = $video->addTextTrack("captions", "Captions", "en");
307             $track->mode = "showing";
308              
309             my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
310             $cue1->snapToLines = 1; # true
311             say( $cue1->snapToLines );
312              
313             $track->addCue( $cue1 );
314              
315             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VTTCue/snapToLines>
316              
317             =head2 startTime
318              
319             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, C<startTime> will be 50.0.
320             C<endTime>
321              
322             =head2 text
323              
324             Returns a string with the contents of the cue.
325              
326             Example:
327              
328             my $video = $doc->querySelector('video');
329             my $track = $video->addTextTrack("captions", "Captions", "en");
330             $track->mode = "showing";
331              
332             my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
333             $cue1->text = 'new cue value';
334             say( $cue1->text ) # 'new cue value';
335              
336             $track->addCue( $cue1 );
337              
338             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VTTCue/text>
339              
340             =head2 vertical
341              
342             Returns an enum representing the cue writing direction.
343              
344             Example:
345              
346             my $video = $doc->querySelector('video');
347             my $track = $video->addTextTrack("captions", "Captions", "en");
348             $track->mode = "showing";
349              
350             my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
351             $cue1->vertical = 'rl';
352             say( $cue1->vertical );
353              
354             $track->addCue( $cue1 );
355              
356             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VTTCue/vertical>
357              
358             =head1 METHODS
359              
360             Inherits methods from its parent L<HTML::Object::Element>
361              
362             =head2 getCueAsHTML
363              
364             Returns the cue text as a L<HTML::Object::DOM::DocumentFragment>.
365              
366             Example:
367              
368             my $video = $doc->querySelector('video');
369             my $track = $video->addTextTrack("captions", "Captions", "en");
370             $track->mode = "showing";
371              
372             my $cue1 = HTML::Object::DOM::VTTCue->new( 0, 0.9, 'Hildy!' );
373             say( $cue1->getCueAsHTML() );
374              
375             $track->addCue( $cue1 );
376              
377             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VTTCue/getCueAsHTML>
378              
379             =head1 AUTHOR
380              
381             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
382              
383             =head1 SEE ALSO
384              
385             L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VTTCue>, L<W3C specifications|https://www.w3.org/TR/webvtt1/>, L<Specifications|https://w3c.github.io/webvtt/#the-vttcue-interface>
386              
387             =head1 COPYRIGHT & LICENSE
388              
389             Copyright(c) 2021 DEGUEST Pte. Ltd.
390              
391             All rights reserved
392              
393             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
394              
395             =cut