File Coverage

lib/HTML/Object/DOM/VideoTrack.pm
Criterion Covered Total %
statement 22 41 53.6
branch 0 8 0.0
condition 0 3 0.0
subroutine 8 12 66.6
pod 3 3 100.0
total 33 67 49.2


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## HTML Object - ~/lib/HTML/Object/DOM/VideoTrack.pm
3             ## Version v0.2.0
4             ## Copyright(c) 2021 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <jack@deguest.jp>
6             ## Created 2021/12/28
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::VideoTrack;
15             BEGIN
16             {
17 1     1   959 use strict;
  1         3  
  1         30  
18 1     1   5 use warnings;
  1         2  
  1         39  
19 1     1   6 use parent qw( HTML::Object::EventTarget );
  1         2  
  1         6  
20 1     1   60 use vars qw( $VERSION );
  1         2  
  1         50  
21 1     1   7 use HTML::Object::Exception;
  1         3  
  1         7  
22 1     1   299 our $VERSION = 'v0.2.0';
23             };
24              
25 1     1   5 use strict;
  1         3  
  1         18  
26 1     1   4 use warnings;
  1         2  
  1         375  
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             # If set, this should be the same as the id in HTML::Object::DOM::Element::Track
43 0           $self->{id} = undef;
44 0           $self->{kind} = $kind;
45 0           $self->{label} = $label;
46 0           $self->{language} = $lang;
47 0           $self->{_init_strict_use_sub} = 1;
48 0 0         $self->SUPER::init( @_ ) || return( $self->pass_error );
49 0           return( $self );
50             }
51              
52             # Note: property id inherited
53              
54             # Note: property kind inherited
55              
56             # Note: property label inherited
57              
58             # Note: property language inherited
59              
60             # Note: property
61             sub selected : lvalue { return( shift->_set_get_boolean({
62             field => 'selected',
63             callbacks =>
64             {
65             add => sub
66             {
67 0     0     my $me = shift( @_ );
68 0           my $parent;
69 0 0 0       if( ( $parent = $me->parent ) && ( my $coderef = $parent->can( '_update_selected' ) ) )
70             {
71 0           $coderef->( $parent, $me );
72             }
73             }
74             }
75 0     0 1   }, @_ ) ); }
76              
77             # Note: property
78 0     0 1   sub sourceBuffer { return; }
79              
80             1;
81             # NOTE: POD
82             __END__
83              
84             =encoding utf-8
85              
86             =head1 NAME
87              
88             HTML::Object::DOM::VideoTrack - HTML Object DOM VideoTrack Class
89              
90             =head1 SYNOPSIS
91              
92             use HTML::Object::DOM::VideoTrack;
93             my $track = HTML::Object::DOM::VideoTrack->new ||
94             die( HTML::Object::DOM::VideoTrack->error, "\n" );
95              
96             =head1 VERSION
97              
98             v0.2.0
99              
100             =head1 DESCRIPTION
101              
102             The C<VideoTrack> interface represents a single video track from a <video> element.
103              
104             To get a C<VideoTrack> for a given media element, use the element's L<videoTracks|HTML::Object::DOM::Element::Media/videoTracks> property, which returns a L<VideoTrackList|HTML::Object::DOM::VideoTrackList> object from which you can get the individual tracks contained in the media:
105              
106             my $el = $doc->querySelector('video');
107             my $tracks = $el->videoTracks;
108             my $firstTrack = $tracks->[0];
109              
110             Scan through all of the media's video tracks, activating the first video track that is in the user's preferred language (taken from a variable userLanguage).
111              
112             for( my $i = 0; $i < $tracks->length; $i++ )
113             {
114             if( $tracks->[$i]->language eq $userLanguage )
115             {
116             $tracks->[$i]->selected = 1; # true
117             last;
118             }
119             });
120              
121             =head1 INHERITANCE
122              
123             +-----------------------+ +---------------------------+ +-------------------------------+
124             | HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::VideoTrack |
125             +-----------------------+ +---------------------------+ +-------------------------------+
126              
127             =head1 PROPERTIES
128              
129             Inherits properties from its parent L<HTML::Object::EventTarget>
130              
131             =head2 id
132              
133             Sets or gets a string which uniquely identifies the track within the media. This ID can be used to locate a specific track within a video track list by calling C<VideoTrackList>.getTrackById(). The ID can also be used as the fragment part of the URL if the media supports seeking by media fragment per the Media Fragments URI specification.
134              
135             Returns the ID as a L<scalar object|Module::Generic::Scalar>
136              
137             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VideoTrack/id>
138              
139             =head2 kind
140              
141             A string specifying the category into which the track falls. For example, the main video track would have a kind of C<main>.
142              
143             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VideoTrack/kind>
144              
145             =head2 label
146              
147             A string providing a human-readable label for the track. For example, a track whose kind is C<sign> might have a label of "A sign-language interpretation". This string is empty if no label is provided.
148              
149             Example:
150              
151             use Module::Generic::Array;
152             sub getTrackList
153             {
154             my $el = shift( @_ );
155             my $trackList = Module::Generic::Array->new;
156             my $wantedKinds = [qw( main alternative commentary )];
157              
158             $el->videoTracks->forEach(sub
159             {
160             my $track = shift( @_ );
161             if( $wantedKinds->includes( $track->kind ) )
162             {
163             $trackList->push({
164             id => $track->id,
165             kind => $track->kind,
166             label => $track->label
167             });
168             }
169             });
170             return( $trackList );
171             }
172              
173             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VideoTrack/label>
174              
175             =head2 language
176              
177             A string specifying the video track's primary language, or an empty string if unknown. The language is specified as a BCP 47 (L<RFC 5646|https://datatracker.ietf.org/doc/html/rfc5646>) language code, such as C<en-US> or C<ja-JP>.
178              
179             Returns the language as a L<scalar object|Module::Generic::Scalar>
180              
181             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VideoTrack/language>
182              
183             =head2 selected
184              
185             A boolean value which controls whether or not the video track is active. Only a single video track can be active at any given time, so setting this property to true for one track while another track is active will make that other track inactive.
186              
187             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VideoTrack/selected>
188              
189             =head2 sourceBuffer
190              
191             This always returns C<undef> under perl.
192              
193             Normally, under JavaScript, this is the C<SourceBuffer> that created the track. Returns C<undef> if the track was not created by a C<SourceBuffer> or the C<SourceBuffer> has been removed from the C<MediaSource.sourceBuffers> attribute of its parent media source.
194              
195             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VideoTrack/sourceBuffer>
196              
197             =head1 METHODS
198              
199             Inherits methods from its parent L<HTML::Object::EventTarget>
200              
201             =head1 AUTHOR
202              
203             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
204              
205             =head1 SEE ALSO
206              
207             L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/VideoTrack>
208              
209             =head1 COPYRIGHT & LICENSE
210              
211             Copyright(c) 2021 DEGUEST Pte. Ltd.
212              
213             All rights reserved
214              
215             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
216              
217             =cut