File Coverage

lib/HTML/Object/DOM/AudioTrack.pm
Criterion Covered Total %
statement 22 37 59.4
branch 0 6 0.0
condition n/a
subroutine 8 11 72.7
pod 3 3 100.0
total 33 57 57.8


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## HTML Object - ~/lib/HTML/Object/DOM/AudioTrack.pm
3             ## Version v0.2.0
4             ## Copyright(c) 2021 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <jack@deguest.jp>
6             ## Created 2021/12/29
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::AudioTrack;
15             BEGIN
16             {
17 1     1   961 use strict;
  1         3  
  1         29  
18 1     1   5 use warnings;
  1         1  
  1         50  
19 1     1   6 use parent qw( HTML::Object::DOM::MediaTrack );
  1         2  
  1         4  
20 1     1   49 use vars qw( $VERSION );
  1         2  
  1         42  
21 1     1   5 use HTML::Object::Exception;
  1         2  
  1         7  
22 1     1   337 our $VERSION = 'v0.2.0';
23             };
24              
25 1     1   6 use strict;
  1         2  
  1         19  
26 1     1   4 use warnings;
  1         4  
  1         253  
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
53 0     0 1   sub enabled : lvalue { return( shift->_set_get_boolean( 'enabled', @_ ) ); }
54              
55             # Note: property id inherited
56              
57             # Note: property kind inherited
58              
59             # Note: property label inherited
60              
61             # Note: property language inherited
62              
63             # Note: property
64 0     0 1   sub sourceBuffer { return; }
65              
66             1;
67             # NOTE: POD
68             __END__
69              
70             =encoding utf-8
71              
72             =head1 NAME
73              
74             HTML::Object::DOM::AudioTrack - HTML Object DOM AudioTrack Class
75              
76             =head1 SYNOPSIS
77              
78             use HTML::Object::DOM::AudioTrack;
79             my $audio = HTML::Object::DOM::AudioTrack->new ||
80             die( HTML::Object::DOM::AudioTrack->error, "\n" );
81              
82             =head1 VERSION
83              
84             v0.2.0
85              
86             =head1 DESCRIPTION
87              
88             The C<AudioTrack> interface represents a single audio track from one of the HTML media elements, <audio> or <video>.
89              
90             =head1 INHERITANCE
91              
92             +-----------------------+ +---------------------------+ +-------------------------------+ +-------------------------------+
93             | HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::MediaTrack | --> | HTML::Object::DOM::AudioTrack |
94             +-----------------------+ +---------------------------+ +-------------------------------+ +-------------------------------+
95              
96             =head1 PROPERTIES
97              
98             Inherits properties from its parent L<HTML::Object::DOM::MediaTrack>
99              
100             =head2 enabled
101              
102             A boolean value which controls whether or not the audio track's sound is enabled. Setting this value to false mutes the track's audio.
103              
104             Example:
105              
106             sub swapCommentaryMain
107             {
108             my $videoElem = $doc->getElementById( 'main-video' );
109             my $audioTrackMain;
110             my $audioTrackCommentary;
111              
112             $videoElem->audioTracks->forEach(sub
113             {
114             my $track = shift( @_ );
115             if( $track->kind == 'main' )
116             {
117             $audioTrackMain = $track;
118             }
119             elsif( $track->kind == 'commentary' )
120             {
121             $audioTrackCommentary = $track;
122             }
123             });
124              
125             if( $audioTrackMain && $audioTrackCommentary )
126             {
127             my $commentaryEnabled = $audioTrackCommentary->enabled;
128             $audioTrackCommentary->enabled = $audioTrackMain->enabled;
129             $audioTrackMain->enabled = $commentaryEnabled;
130             }
131             }
132              
133             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/AudioTrack/enabled>
134              
135             =head2 id
136              
137             A string which uniquely identifies the track within the media. This ID can be used to locate a specific track within an audio track list by calling C<AudioTrackList>.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.
138              
139             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/AudioTrack/id>
140              
141             =head2 kind
142              
143             A string specifying the category into which the track falls. For example, the main audio track would have a kind of "main".
144              
145             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/AudioTrack/kind>
146              
147             =head2 label
148              
149             A string providing a human-readable label for the track. For example, an audio commentary track for a movie might have a label of "Commentary with director John Q. Public and actors John Doe and Jane Eod." This string is empty if no label is provided.
150              
151             Example:
152              
153             use Module::Generic::Array;
154             sub getTrackList
155             {
156             my $el = shift( @_ );
157             my $trackList = Module::Generic::Array->new;
158             my $wantedKinds = [
159             "main", "alternative", "main-desc", "translation", "commentary"
160             ];
161              
162             $el->audioTracks->forEach(sub
163             {
164             my $track = shift( @_ );
165             if( $wantedKinds->includes( $track->kind ) )
166             {
167             $trackList->push({
168             id => $track->id,
169             kind => $track->kind,
170             label => $track->label
171             });
172             }
173             });
174             return( $trackList );
175             }
176              
177             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/AudioTrack/label>
178              
179             =head2 language
180              
181             A string specifying the audio track's primary language, or an empty string if unknown. The language is specified as a BCP 47 (RFC 5646) language code, such as "en-US" or "pt-BR".
182              
183             Example:
184              
185             use Module::Generic::Array;
186             sub getAvailableLanguages
187             {
188             my $el = shift( @_ );
189             my $trackList = Module::Generic::Array->new;
190             my $wantedKinds = [
191             "main", "translation"
192             ];
193              
194             $el->audioTracks->forEach(sub
195             {
196             my $track = shift( @_ );
197             if( $wantedKinds->includes( $track->kind ) )
198             {
199             $trackList->push({
200             id => $track->id,
201             kind => $track->kind,
202             language => $track->language
203             });
204             }
205             });
206             return( $trackList );
207             }
208              
209             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/AudioTrack/language>
210              
211             =head2 sourceBuffer
212              
213             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.
214              
215             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/AudioTrack/sourceBuffer>
216              
217             =head1 METHODS
218              
219             Inherits methods from its parent L<HTML::Object::DOM::MediaTrack>
220              
221             =head1 EXAMPLE
222              
223             use feature 'signatures';
224             my $sfx = HTML::Object::DOM::Element::Audio->new( 'sfx.wav' );
225             my $sounds = $sfx->addTextTrack( 'metadata' );
226              
227             # add sounds we care about
228             sub addFX( $start, $end, $name )
229             {
230             my $cue = HTML::Object::DOM::VTTCue->new( $start, $end, '' );
231             $cue->id = $name;
232             $cue->pauseOnExit = 1; # true
233             $sounds->addCue( $cue );
234             }
235             addFX( 12.783, 13.612, 'dog bark' );
236             addFX( 13.612, 15.091, 'kitten mew' );
237              
238             sub playSound( $id )
239             {
240             $sfx->currentTime = $sounds->getCueById( $id )->startTime;
241             $sfx->play();
242             }
243              
244             # play a bark as soon as we can
245             $sfx->oncanplaythrough = sub
246             {
247             playSound( 'dog bark' );
248             }
249             # meow when the user tries to leave,
250             # and have the browser ask them to stay
251             $doc->onbeforeunload = sub
252             {
253             my $e = shift( @_ );
254             playSound( 'kitten mew' );
255             $e->preventDefault();
256             }
257              
258             =head1 AUTHOR
259              
260             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
261              
262             =head1 SEE ALSO
263              
264             L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/AudioTrack>
265              
266             =head1 COPYRIGHT & LICENSE
267              
268             Copyright(c) 2021 DEGUEST Pte. Ltd.
269              
270             All rights reserved
271              
272             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
273              
274             =cut