StreamFinder/Castbox.pm untested

filter: Statementstmt 0.0% 0 / 156 Branchbran 0.0% 0 / 110 Conditioncond 0.0% 0 / 33 MC/DCmcdc 0.0% 0 / 22 Subroutinesub 0.0% 0 / 7 Podpod 0.0% 0 / 1 totaltotal 0.0% 0 / 329 CC 56 SCAR 79.7
CC
56
Cov
0%
new
3192.0
BEGIN
2.0
BEGIN
2.0
CRAP 2883.3
1 =head1 NAME
2  
3 StreamFinder::Castbox - Fetch actual raw streamable podcast URLs on castbox.fm
4  
5 =head1 AUTHOR
6  
7 This module is Copyright (C) 2021-2026 by
8  
9 Jim Turner, C<< <turnerjw784 at yahoo.com> >>
10
11 Email: turnerjw784@yahoo.com
12  
13 All rights reserved.
14  
15 You may distribute this module under the terms of either the GNU General
16 Public License or the Artistic License, as specified in the Perl README
17 file.
18  
19 =head1 SYNOPSIS
20  
21 #!/usr/bin/perl
22  
23 use strict;
24  
25 use StreamFinder::Castbox;
26  
27 die "..usage: $0 URL\n" unless ($ARGV[0]);
28  
29 my $podcast = new StreamFinder::Castbox($ARGV[0]);
30  
31 die "Invalid URL or no streams found!\n" unless ($podcast);
32  
33 my $firstStream = $podcast->get();
34  
35 print "First Stream URL=$firstStream\n";
36  
37 my $url = $podcast->getURL();
38  
39 print "Stream URL=$url\n";
40  
41 my $podcastTitle = $podcast->getTitle();
42
43 print "Title=$podcastTitle\n";
44
45 my $podcastDescription = $podcast->getTitle('desc');
46
47 print "Description=$podcastDescription\n";
48
49 my $podcastID = $podcast->getID();
50  
51 print "Podcast ID=$podcastID\n";
52
53 my $icon_url = $podcast->getIconURL();
54  
55 if ($icon_url) { #SAVE THE ICON TO A TEMP. FILE:
56  
57 print "Icon URL=$icon_url=\n";
58  
59 my ($image_ext, $icon_image) = $podcast->getIconData();
60  
61 if ($icon_image && open IMGOUT, ">/tmp/${podcastID}.$image_ext") {
62  
63 binmode IMGOUT;
64  
65 print IMGOUT $icon_image;
66  
67 close IMGOUT;
68  
69 print "...Icon image downloaded to (/tmp/${podcastID}.$image_ext)\n";
70  
71 }
72  
73 }
74  
75 my $stream_count = $podcast->count();
76  
77 print "--Stream count=$stream_count=\n";
78  
79 my @streams = $podcast->get();
80  
81 foreach my $s (@streams) {
82  
83 print "------ stream URL=$s=\n";
84  
85 }
86  
87 =head1 DESCRIPTION
88  
89 StreamFinder::Castbox accepts a valid podcast ID or URL on
90 Castbox.fm and returns the actual stream URL(s), title, and cover art icon.
91 The purpose is that one needs one of these URLs in order to have the option to
92 stream the podcast in one's own choice of media player software rather than
93 using their web browser and accepting any / all flash, ads, javascript,
94 cookies, trackers, web-bugs, and other crapware that can come with that method
95 of play. The author uses his own custom all-purpose media player called
96 "fauxdacious" (his custom hacked version of the open-source "audacious"
97 audio player). "fauxdacious" can incorporate this module to decode and play
98 Castbox.fm streams.
99  
100 One or more stream URLs can be returned for each podcast.
101  
102 =head1 SUBROUTINES/METHODS
103  
104 =over 4
105  
106 =item B<new>(I<url> [, I<-secure> [ => 0|1 ]] [, I<-debug> [ => 0|1|2 ] ... ])
107  
108 Accepts a www.castbox.fm podcast URL and creates and returns a
109 a new podcast object, or I<undef> if the URL is not a valid podcast, or no
110 streams are found. The URL MUST be the full URL, ie.
111 I<https://castbox.fm/episode/>B<title>-idB<channel-id>-idB<episode-id>, or
112 I<https://castbox.fm/channel/id>B<channel-id>
113 as I know of no way to look up a podcast on Castbox with just an episode ID.
114 If no I<episode-id> is specified, the first (latest) episode for the channel
115 is returned.
116  
117 The optional I<-secure> argument can be either 0 or 1 (I<false> or I<true>).
118 If 1 then only secure ("https://") streams will be returned.
119  
120 DEFAULT I<-secure> is 0 (false) - return all streams (http and https).
121  
122 Additional options:
123  
124 I<-log> => "I<logfile>"
125  
126 Specify path to a log file. If a valid and writable file is specified, A line
127 will be appended to this file every time one or more streams is successfully
128 fetched for a url.
129  
130 DEFAULT I<-none-> (no logging).
131  
132 I<-logfmt> specifies a format string for lines written to the log file.
133  
134 DEFAULT "I<[time] [url] - [site]: [title] ([total])>".
135  
136 The valid field I<[variables]> are: [stream]: The url of the first/best
137 stream found. [site]: The site name (Castbox). [url]: The url searched for
138 streams. [time]: Perl timestamp when the line was logged. [title], [artist],
139 [album], [description], [year], [genre], [total], [albumartist]: The
140 corresponding field data returned (or "I<-na->", if no value).
141  
142 =item $podcast->B<get>(['playlist'])
143  
144 Returns an array of strings representing all stream URLs found.
145 If I<"playlist"> is specified, then an extended m3u playlist is returned
146 instead of stream url(s). NOTE: If an author / channel page url is given,
147 rather than an individual podcast episode's url, get() returns the first
148 (latest?) podcast episode found, and get("playlist") returns an extended
149 m3u playlist containing the urls, titles, etc. for all the podcast
150 episodes found on that page url.
151  
152 =item $podcast->B<getURL>([I<options>])
153  
154 Similar to B<get>() except it only returns a single stream representing
155 the first valid stream found. There currently are no valid I<options>.
156  
157 =item $podcast->B<count>(['playlist'])
158  
159 Returns the number of streams found for the podcast.
160 If I<"playlist"> is specified, the number of episodes returned in the
161 playlist is returned (the playlist can have more than one item if a
162 podcast page URL is specified).
163  
164 =item $podcast->B<getID>()
165  
166 Returns the podcast's Castbox ID (default). For podcasts, the Castbox ID
167 is a single value. For individual podcast episodes it's two values
168 separated by a slash ("/").
169  
170 =item $podcast->B<getTitle>(['desc'])
171  
172 Returns the podcast's title, or (long description). Podcasts
173 on Castbox can have separate descriptions, but for podcasts,
174 it is always the podcast's title.
175  
176 Note: Castbox podcasts sometimes contain a transcript text in a "lyrics"
177 (.lrc) link, which we download and append to the long description field.
178 This is useful in media players like Fauxdacious which display the
179 description field for podcasts and videos in the place where song lyrics
180 are displayed for songs. If this is undesirable, one can simply add
181 something like "$podcast->{'description'} =~ s#\n\nTranscript:.+$##s;"
182 in their code.
183  
184 =item $podcast->B<getIconURL>(['artist'])
185  
186 Returns the URL for the podcast's "cover art" icon image, if any.
187 If B<'artist'> is specified, the channel artist's icon url is returned,
188 if any.
189  
190 =item $podcast->B<getIconData>(['artist'])
191  
192 Returns a two-element array consisting of the extension (ie. "png",
193 "gif", "jpeg", etc.) and the actual icon image (binary data), if any.
194 If B<'artist'> is specified, the channel artist's icon data is returned,
195 if any.
196  
197 =item $podcast->B<getImageURL>()
198  
199 Returns the URL for the podcast's "cover art" (usually larger)
200 banner image.
201  
202 =item $podcast->B<getImageData>()
203  
204 Returns a two-element array consisting of the extension (ie. "png",
205 "gif", "jpeg", etc.) and the actual podcast's banner image (binary data).
206  
207 =item $podcast->B<getType>()
208  
209 Returns the podcast's type ("Castbox").
210  
211 =back
212  
213 =head1 CONFIGURATION FILES
214  
215 The default root location directory for StreamFinder configuration files
216 is "~/.config/StreamFinder". To use an alternate location directory,
217 specify it in the "I<STREAMFINDER>" environment variable, ie.:
218 B<$ENV{STREAMFINDER} = "/etc/StreamFinder">.
219  
220 =over 4
221  
222 =item ~/.config/StreamFinder/Castbox/config
223  
224 Optional text file for specifying various configuration options
225 for a specific site (submodule). Each option is specified on a
226 separate line in the format below:
227 NOTE: Do not follow the lines with a semicolon, comma, or any other
228 separator. Non-numeric I<values> should be surrounded with quotes, either
229 single or double. Blank lines and lines beginning with a "#" sign as
230 their first non-blank character are ignored as comments.
231  
232 'option' => 'value' [,]
233  
234 and the options are loaded into a hash used only by the specific
235 (submodule) specified. Valid options include
236 I<-debug> => [0|1|2] and most of the L<LWP::UserAgent> options.
237  
238 Options specified here override any specified in
239 I<~/.config/StreamFinder/config>.
240  
241 =item ~/.config/StreamFinder/config
242  
243 Optional text file for specifying various configuration options.
244 Each option is specified on a separate line in the format below:
245  
246 'option' => 'value' [,]
247  
248 and the options are loaded into a hash used by all sites
249 (submodules) that support them. Valid options include
250 I<-debug> => [0|1|2] and most of the L<LWP::UserAgent> options.
251  
252 =back
253  
254 NOTE: Options specified in the options parameter list of the I<new()>
255 function will override those corresponding options specified in these files.
256  
257 =head1 KEYWORDS
258  
259 castbox
260  
261 =head1 DEPENDENCIES
262  
263 L<URI::Escape>, L<HTML::Entities>, L<LWP::UserAgent>
264  
265 =head1 RECCOMENDS
266  
267 wget
268  
269 =head1 BUGS
270  
271 Please report any bugs or feature requests to C<bug-streamFinder-iheartradio at rt.cpan.org>, or through
272 the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=StreamFinder-Castbox>. I will be notified, and then you'll
273 automatically be notified of progress on your bug as I make changes.
274  
275 =head1 SUPPORT
276  
277 You can find documentation for this module with the perldoc command.
278  
279 perldoc StreamFinder::Castbox
280  
281 You can also look for information at:
282  
283 =over 4
284  
285 =item * RT: CPAN's request tracker (report bugs here)
286  
287 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=StreamFinder-Castbox>
288  
289 =item * AnnoCPAN: Annotated CPAN documentation
290  
291 L<http://annocpan.org/dist/StreamFinder-Castbox>
292  
293 =item * Search CPAN
294  
295 L<http://search.cpan.org/dist/StreamFinder-Castbox/>
296  
297 =back
298  
299 =head1 LICENSE AND COPYRIGHT
300  
301 Copyright 2021-2026 Jim Turner.
302  
303 This program is free software; you can redistribute it and/or modify it
304 under the terms of the the Artistic License (2.0). You may obtain a
305 copy of the full license at:
306  
307 L<http://www.perlfoundation.org/artistic_license_2_0>
308  
309 Any use, modification, and distribution of the Standard or Modified
310 Versions is governed by this Artistic License. By using, modifying or
311 distributing the Package, you accept this license. Do not use, modify,
312 or distribute the Package, if you do not accept this license.
313  
314 If your Modified Version has been derived from a Modified Version made
315 by someone other than you, you are nevertheless required to ensure that
316 your Modified Version complies with the requirements of this license.
317  
318 This license does not grant you the right to use any trademark, service
319 mark, tradename, or logo of the Copyright Holder.
320  
321 This license includes the non-exclusive, worldwide, free-of-charge
322 patent license to make, have made, use, offer to sell, sell, import and
323 otherwise transfer the Package with respect to any patent claims
324 licensable by the Copyright Holder that are necessarily infringed by the
325 Package. If you institute patent litigation (including a cross-claim or
326 counterclaim) against any party alleging that the Package constitutes
327 direct or contributory patent infringement, then this Artistic License
328 to you shall terminate on the date that such litigation is filed.
329  
330 Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER
331 AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.
332 THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
333 PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY
334 YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR
335 CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR
336 CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE,
337 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
338  
339 =cut
340  
341 package StreamFinder::Castbox;
342  
343 use strict;
344 use warnings;
345 use URI::Escape;
346 use HTML::Entities ();
347 use LWP::UserAgent ();
348 use parent 'StreamFinder::_Class';
349  
350 my $DEBUG = 0;
351  
352 sub new
353 {
354 my $class = shift;
355 my $url = shift;
356  
357 return undef unless ($url);
358  
359 my $self = $class->SUPER::new('Castbox', @_);
360 $DEBUG = $self->{'debug'} if (defined $self->{'debug'});
361  
362 $self->{'id'} = '';
363 my $urlroot = '';
364 (my $url2fetch = $url);
365 if ($url2fetch =~ m#^(https?\:\/\/castbox\.\w+)#) {
366 $urlroot = $1;
367 $self->{'id'} = ($url =~ m#\-id(\d+)\-id(\d+)#) ? "${1}/$2" : '';
368 $self->{'id'} ||= $1 if ($url =~ m#id(\d+)#); #NO EPISODE SPECIFIED
369 } else {
370 $self->{'id'} = $url2fetch;
371 }
372 unless ($self->{'id'}) { #MUST PROVIDE URL, NO KNOWN WAY TO LOOK UP WITH JUST ID#?!
373 print STDERR "w:No ID found - url ($url) is NOT a valid Castbox podcast url!\n" if ($DEBUG);
374 return undef;
375 }
376  
377 my ($channelID, $episodeID);
378 if ($self->{'id'} =~ m#^(\d+)\/(\d+)$#) { #SPECIFIC EPISODE GIVEN:
379 $channelID = $1;
380 $episodeID = $2;
381 $url2fetch = s#\/episode\/.+$#\/channel\/id$channelID\/#;
382 } else { #PODCAST PAGE ID GIVEN:
383 $channelID = $self->{'id'};
384 }
385 #NOTE: FOR Castbox PODCASTS & EPISODES, WE SCRAPE ALL NEEDED DATA FROM THE PODCAST CHANNEL PAGE,
386 #AS EPISODE PAGES ARE NO LONGER SCRAPABLE:
387 $url2fetch = 'https://castbox.fm/channel/id' . $channelID
388 unless ($url2fetch =~ m#\/channel\/#);
389  
390 my $html = '';
391 print STDERR "-0(Castbox): FETCHING URL=$url2fetch= ID=".$self->{'id'}."=\n" if ($DEBUG);
392 my $ua = LWP::UserAgent->new(@{$self->{'_userAgentOps'}});
393 $ua->timeout($self->{'timeout'});
394 $ua->cookie_jar({});
395 $ua->env_proxy;
396 my $response;
397 $self->{'genre'} = 'Podcast';
398 $self->{'albumartist'} = $url2fetch;
399 my @epiTitles = ();
400 my @epiStreams = ();
401  
402 $response = $ua->get($url2fetch);
403 if ($response->is_success) {
404 $html = $response->decoded_content;
405 } else {
406 print STDERR $response->status_line if ($DEBUG);
407 }
408 print STDERR "-1: html=$html=\n" if ($DEBUG > 1);
409 return undef unless ($html && $self->{'id'}); #STEP 1 FAILED, INVALID PODCAST URL, PUNT!
410  
411 #FETCH PODCAST CHANNEL DATA:
412 $self->{'album'} = $1 if ($html =~ m#\<h1\s+title\=\"([^\"]+)#);
413 $self->{'albumartist'} = $url2fetch;
414 $self->{'articonurl'} = ($html =~ s#\<meta\s+property\=\"(?:og|twitter)\:image\"\s+content\=\"([^\"]+)\"\s*\/\>##s) ? $1 : '';
415 $self->{'articonurl'} ||= $1 if ($html =~ s#\"\,\"image\"\:\"([^\"]+)\"\}\}\]\}##s);
416 $self->{'artimageurl'} ||= $self->{'articonurl'};
417 #FETCH ALL EPISODE DATA:
418 $html =~ s#^.+?\_\_INITIAL\_STATE\_\_##s; #EPISODE DATA IS AFTER HERE:
419 $html = uri_unescape($html);
420 $self->{'genre'} = $1 if ($html =~ m#\"keywords\"\:\[?\"([^\"]+)#);
421 unless (defined $episodeID) {
422 $episodeID = $1 if ($html =~ /\{\"latest\_eid\"\:(\d+)/);
423 }
424 my $epiID;
425 my $haveit = 0; #TRUE WHEN WE HAVE DETAILED DATA FOR THE LATEST EPISODE.
426 while ($html =~ s#^.+?\{\"website\"\:##s) {
427 (my $ephtml = $html) =~ s/\{\"website\"\:.*$//so;
428 next unless ($ephtml =~ /\"eid\"\:(\d+)/so);
429 $epiID = $1;
430 print STDERR "---NEXT EPISODEID=$epiID= EPISODE=$episodeID=\n" if ($DEBUG);
431 my $stream = '';
432 my $title = '';
433 if ($ephtml =~ m#\,\"url\"\:\"([^\"]+)\"#so) {
434 $stream = $1;
435 } elsif ($ephtml =~ m#\,\"urls\"\:\[\"([^\"]+)\"#so) {
436 $stream = $1;
437 }
438 if ($stream && $ephtml =~ s#\"title\"\:\"([^\"]+)\"##s) {
439 my $one = $1;
440 unless ($self->{'secure'} && $stream !~ /^https/o) {
441 push @epiTitles, $one; #ADD ALL EPISODES TO THE PLAYLIST:
442 push @epiStreams, $stream;
443 if (!$haveit && (!defined($episodeID) || $episodeID == $epiID)) {
444 #GRAB 1ST/LATEST EPISODE DETAILS:
445 $episodeID = $epiID;
446 $haveit = 1;
447 $self->{'title'} = $one;
448 $self->{'title'} = HTML::Entities::decode_entities($self->{'title'});
449 $self->{'title'} =~ s/(?:\%|\\[ux\%]?00|\bu00)([0-9A-Fa-f]{2})/chr(hex($1))/egs;;
450 print STDERR "-----GRABBED THIS EPISODE=$epiID!= TITLE=$$self{'title'}= stream=$stream\n" if ($DEBUG);
451 $self->{'artist'} = $1 if ($ephtml =~ m#\"author\"\:\"([^\"]+)\"#so);
452 $self->{'description'} = $1 if ($ephtml =~ m#\"description\"\:\"([^\"]+)\"#so);
453 $self->{'description'} = HTML::Entities::decode_entities($self->{'description'});
454 $self->{'description'} =~ s/(?:\%|\\[ux\%]?00|\bu00)([0-9A-Fa-f]{2})/chr(hex($1))/egs;
455 $self->{'description'} =~ s#\\$##gs;
456 $self->{'iconurl'} = $1 if ($ephtml =~ m#\"cover\_url\"\:\"([^\"]+)\"#so);
457 $self->{'iconurl'} ||= $1 if ($ephtml =~ m#\"small\_cover\_url\"\:\"([^\"]+)\"#so);
458 $self->{'imageurl'} = $1 if ($ephtml =~ m#\"big\_cover\_url\"\:\"([^\"]+)\"#so);
459 $self->{'iconurl'} ||= $self->{'imageurl'};
460 $self->{'imageurl'} ||= $self->{'iconurl'};
461 $self->{'created'} = $1 if ($ephtml =~ m#\"release\_date\"\:\"([^\"]+)\"#so);
462 $self->{'year'} = $1 if ($self->{'created'} =~ /(\d\d\d\d)/o);
463 push @{$self->{'streams'}}, $stream;
464 $self->{'cnt'}++;
465 $self->{'lyricURL'} = ($ephtml =~ m#\,\{\"url\"\:\"([^\"]+?\.lrc)\"#) ? $1 : '';
466 }
467 }
468 }
469 }
470 print STDERR "-(all)count=".$self->{'cnt'}."= iconurl=".$self->{'iconurl'}."= TITLE=".$self->{'title'}."= DESC=".$self->{'description'}."= YEAR=".$self->{'year'}."= artist=".$self->{'artist'}."= albart=".$self->{'albumartist'}."=\n" if ($DEBUG);
471 return undef unless ($self->{'cnt'} > 0);
472  
473 $self->{'total'} = $self->{'cnt'};
474 $self->{'Url'} = ($self->{'total'} > 0) ? $self->{'streams'}->[0] : '';
475 print STDERR "--SUCCESS: 1st stream=".$self->{'Url'}."= total=".$self->{'total'}."=\n" if ($DEBUG);
476 $self->{'playlist'} = "#EXTM3U\n";
477 if ($#epiStreams >= 0) { #PLAYLIST PAGE SPECIFIED, ADD ALL EPISODES TO PLAYLIST:
478 $self->{'playlist_cnt'} = scalar @epiStreams;
479 for (my $i=0;$i<=$#epiStreams;$i++) {
480 last if ($i > $#epiTitles);
481 $self->{'playlist'} .= "#EXTINF:-1, " . $epiTitles[$i] . "\n";
482 $self->{'playlist'} .= "#EXTART:" . $self->{'artist'} . "\n"
483 if ($self->{'artist'});
484 $self->{'playlist'} .= "#EXTALB:" . $self->{'album'} . "\n"
485 if ($self->{'album'});
486 $self->{'playlist'} .= "#EXTGENRE:" . $self->{'genre'} . "\n"
487 if ($self->{'genre'});
488 $self->{'playlist'} .= $epiStreams[$i] . "\n";
489 }
490 } else { #EPISODE PAGE SPECIFIED, ONLY THAT EPISODE ADDED TO PLAYLIST:
491 $self->{'playlist_cnt'} = 1;
492 $self->{'playlist'} .= "#EXTINF:-1, " . $self->{'title'} . "\n";
493 $self->{'playlist'} .= "#EXTART:" . $self->{'artist'} . "\n"
494 if ($self->{'artist'});
495 $self->{'playlist'} .= "#EXTALB:" . $self->{'album'} . "\n"
496 if ($self->{'album'});
497 $self->{'playlist'} .= "#EXTGENRE:" . $self->{'genre'} . "\n"
498 if ($self->{'genre'});
499 $self->{'playlist'} .= ${$self->{'streams'}}[0] . "\n";
500 }
501 if ($self->{'lyricURL'}) { #HAVE LYRICS?!:
502 $response = $ua->get($self->{'lyricURL'});
503 if ($response->is_success) {
504 my $lyrics = $response->decoded_content;
505 if ($lyrics) {
506 print STDERR "--WE HAVE LYRICS!, COOL!\n" if ($DEBUG);
507 $lyrics = HTML::Entities::decode_entities($lyrics);
508 $lyrics =~ s/(?:\%|\\[ux\%]?00|\bu00)([0-9A-Fa-f]{2})/chr(hex($1))/egs;
509 $self->{'description'} .= "\n\nTranscript: $lyrics";
510 }
511 } else {
512 print STDERR $response->status_line if ($DEBUG);
513 }
514 }
515 $self->_log($url);
516 if ($DEBUG) {
517 foreach my $f (sort keys %{$self}) {
518 print STDERR "--KEY=$f= VAL=$$self{$f}=\n";
519 }
520 print STDERR "-SUCCESS: 1st stream=".$self->{'Url'}."=\n" if ($DEBUG);
521 }
522  
523 bless $self, $class; #BLESS IT!
524  
525 return $self;
526 }
527  
528 1