Merge ec8cc20805d856dd4b6e8e098bf007c12e4ec904 into 3eb8d22ddb8982ca4fb56bb7a8d6517538bf14c6

* thx seproDev, yt-dlp/yt-dlp/pull/12694/commits/ae69e3c
* also add documenting comment in `InfoExtractor`

youtube_dl/YoutubeDL.py

@@ -214,6 +214,7 @@ class YoutubeDL(object):
     writeannotations:  Write the video annotations to a .annotations.xml file
     writethumbnail:    Write the thumbnail image to a file
     write_all_thumbnails:  Write all thumbnail formats to files
+    writestoryboards:  Write all storyboards (grid of video frames) to a file
     writesubtitles:    Write the video subtitles to a file
     writeautomaticsub: Write the automatically generated subtitles to a file
     allsubtitles:      Downloads all the subtitles of the video
@@ -310,6 +311,7 @@ class YoutubeDL(object):
                        [sleep_interval; max_sleep_interval].
     listformats:       Print an overview of available video formats and exit.
     list_thumbnails:   Print a table of all thumbnails and exit.
+    list_storyboards:  Print a table of all storyboards and exit.
     match_filter:      A function that gets called with the info_dict of
                        every video.
                        If it returns a message, the video is ignored.
@@ -1693,6 +1695,10 @@ class YoutubeDL(object):
             self.list_thumbnails(info_dict)
             return
 
+        if self.params.get('list_storyboards'):
+            self.list_thumbnails(info_dict, item_name='storyboards')
+            return
+
         thumbnail = info_dict.get('thumbnail')
         if thumbnail:
             info_dict['thumbnail'] = sanitize_url(thumbnail)
@@ -2466,17 +2472,27 @@ class YoutubeDL(object):
             '[info] Available formats for %s:\n%s' %
             (info_dict['id'], render_table(header_line, table)))
 
-    def list_thumbnails(self, info_dict):
+    def list_thumbnails(self, info_dict, item_name='thumbnails'):
-        thumbnails = info_dict.get('thumbnails')
+        thumbnails = info_dict.get(item_name)
         if not thumbnails:
-            self.to_screen('[info] No thumbnails present for %s' % info_dict['id'])
+            self.to_screen('[info] No %s present for %s' % (item_name, info_dict['id']))
             return
 
         self.to_screen(
-            '[info] Thumbnails for %s:' % info_dict['id'])
+            '[info] %s for %s:' % (item_name.title(), info_dict['id']))
-        self.to_screen(render_table(
+
-            ['ID', 'width', 'height', 'URL'],
+        columns = ['ID', 'width', 'height']
-            [[t['id'], t.get('width', 'unknown'), t.get('height', 'unknown'), t['url']] for t in thumbnails]))
+        if item_name == 'storyboards':
+            columns += ['cols', 'rows', 'frames']
+        columns += ['URL']
+
+        table = []
+        for t in thumbnails:
+            table.append([])
+            for column in columns:
+                table[-1].append(t.get(column.lower(), 'unknown'))
+
+        self.to_screen(render_table(columns, table))
 
     def list_subtitles(self, video_id, subtitles, name='subtitles'):
         if not subtitles:
@@ -2679,12 +2695,16 @@ class YoutubeDL(object):
                 return
 
     def _write_thumbnails(self, info_dict, filename):
+        item_name = 'thumbnail'
         if self.params.get('writethumbnail', False):
             thumbnails = info_dict.get('thumbnails')
             if thumbnails:
                 thumbnails = [thumbnails[-1]]
         elif self.params.get('write_all_thumbnails', False):
             thumbnails = info_dict.get('thumbnails')
+        elif self.params.get('writestoryboards', False):
+            thumbnails = info_dict.get('storyboards')
+            item_name = 'storyboard'
         else:
             return
 
@@ -2694,22 +2714,28 @@ class YoutubeDL(object):
 
         for t in thumbnails:
             thumb_ext = determine_ext(t['url'], 'jpg')
+            if item_name == 'thumbnails':
                 suffix = '_%s' % t['id'] if len(thumbnails) > 1 else ''
+            else:
+                suffix = '_%s_%s' % (item_name, t['id'])
             thumb_display_id = '%s ' % t['id'] if len(thumbnails) > 1 else ''
             t['filename'] = thumb_filename = replace_extension(filename + suffix, thumb_ext, info_dict.get('ext'))
 
             if self.params.get('nooverwrites', False) and os.path.exists(encodeFilename(thumb_filename)):
-                self.to_screen('[%s] %s: Thumbnail %sis already present' %
+                self.to_screen('[%s] %s: %s %sis already present' %
-                               (info_dict['extractor'], info_dict['id'], thumb_display_id))
+                               (info_dict['extractor'], info_dict['id'],
+                                item_name.title(), thumb_display_id))
             else:
-                self.to_screen('[%s] %s: Downloading thumbnail %s...' %
+                self.to_screen('[%s] %s: Downloading %s %s...' %
-                               (info_dict['extractor'], info_dict['id'], thumb_display_id))
+                               (info_dict['extractor'], info_dict['id'],
+                                item_name, thumb_display_id))
                 try:
                     uf = self.urlopen(t['url'])
                     with open(encodeFilename(thumb_filename), 'wb') as thumbf:
                         shutil.copyfileobj(uf, thumbf)
-                    self.to_screen('[%s] %s: Writing thumbnail %sto: %s' %
+                    self.to_screen('[%s] %s: Writing %s %sto: %s' %
-                                   (info_dict['extractor'], info_dict['id'], thumb_display_id, thumb_filename))
+                                   (info_dict['extractor'], info_dict['id'],
+                                    item_name, thumb_display_id, thumb_filename))
                 except (compat_urllib_error.URLError, compat_http_client.HTTPException, socket.error) as err:
-                    self.report_warning('Unable to download thumbnail "%s": %s' %
+                    self.report_warning('Unable to download %s "%s": %s' %
-                                        (t['url'], error_to_compat_str(err)))
+                                        (t['url'], item_name, error_to_compat_str(err)))

youtube_dl/__init__.py

@@ -374,6 +374,7 @@ def _real_main(argv=None):
         'writeinfojson': opts.writeinfojson,
         'writethumbnail': opts.writethumbnail,
         'write_all_thumbnails': opts.write_all_thumbnails,
+        'writestoryboards': opts.writestoryboards,
         'writesubtitles': opts.writesubtitles,
         'writeautomaticsub': opts.writeautomaticsub,
         'allsubtitles': opts.allsubtitles,
@@ -421,6 +422,7 @@ def _real_main(argv=None):
         'max_sleep_interval': opts.max_sleep_interval,
         'external_downloader': opts.external_downloader,
         'list_thumbnails': opts.list_thumbnails,
+        'list_storyboards': opts.list_storyboards,
         'playlist_items': opts.playlist_items,
         'xattr_set_filesize': opts.xattr_set_filesize,
         'match_filter': match_filter,

youtube_dl/extractor/bokecc.py

@@ -32,7 +32,7 @@ class BokeCCBaseIE(InfoExtractor):
 
 
 class BokeCCIE(BokeCCBaseIE):
-    _IE_DESC = 'CC视频'
+    IE_DESC = 'CC视频'
     _VALID_URL = r'https?://union\.bokecc\.com/playvideo\.bo\?(?P<query>.*)'
 
     _TESTS = [{

youtube_dl/extractor/cloudy.py

@@ -9,7 +9,7 @@ from ..utils import (
 
 
 class CloudyIE(InfoExtractor):
-    _IE_DESC = 'cloudy.ec'
+    IE_DESC = 'cloudy.ec'
     _VALID_URL = r'https?://(?:www\.)?cloudy\.ec/(?:v/|embed\.php\?.*?\bid=)(?P<id>[A-Za-z0-9]+)'
     _TESTS = [{
         'url': 'https://www.cloudy.ec/v/af511e2527aac',

youtube_dl/extractor/common.py

@@ -239,6 +239,12 @@ class InfoExtractor(object):
                                         deprecated)
                         * "filesize" (optional, int)
     thumbnail:      Full URL to a video thumbnail image.
+    storyboards:    A list of dictionaries representing storyboards.
+                    A storyboard is an image grid made of frames from the video.
+                    This has the same structure as the thumbnails list, plus:
+                        * "cols" (optional, int)
+                        * "rows" (optional, int)
+                        * "frames" (optional, int)
     description:    Full video description.
     uploader:       Full name of the video uploader.
     license:        License name the video is licensed under.
@@ -422,6 +428,8 @@ class InfoExtractor(object):
     _GEO_COUNTRIES = None
     _GEO_IP_BLOCKS = None
     _WORKING = True
+    # supply this in public subclasses: used in supported sites list, etc
+    # IE_DESC = 'short description of IE'
 
     def __init__(self, downloader=None):
         """Constructor. Receives an optional downloader."""

youtube_dl/extractor/itv.py

@@ -35,15 +35,6 @@ from ..utils import (
 
 class ITVBaseIE(InfoExtractor):
 
-    def _search_nextjs_data(self, webpage, video_id, **kw):
-        transform_source = kw.pop('transform_source', None)
-        fatal = kw.pop('fatal', True)
-        return self._parse_json(
-            self._search_regex(
-                r'''<script\b[^>]+\bid=('|")__NEXT_DATA__\1[^>]*>(?P<js>[^<]+)</script>''',
-                webpage, 'next.js data', group='js', fatal=fatal, **kw),
-            video_id, transform_source=transform_source, fatal=fatal)
-
     def __handle_request_webpage_error(self, err, video_id=None, errnote=None, fatal=True):
         if errnote is False:
             return False
@@ -109,7 +100,9 @@ class ITVBaseIE(InfoExtractor):
 
 class ITVIE(ITVBaseIE):
     _VALID_URL = r'https?://(?:www\.)?itv\.com/(?:(?P<w>watch)|hub)/[^/]+/(?(w)[\w-]+/)(?P<id>\w+)'
-    _IE_DESC = 'ITVX'
+    IE_DESC = 'ITVX'
+    _WORKING = False
+
     _TESTS = [{
         'note': 'Hub URLs redirect to ITVX',
         'url': 'https://www.itv.com/hub/liar/2a4547a0012',
@@ -270,7 +263,7 @@ class ITVIE(ITVBaseIE):
                 'ext': determine_ext(href, 'vtt'),
             })
 
-        next_data = self._search_nextjs_data(webpage, video_id, fatal=False, default='{}')
+        next_data = self._search_nextjs_data(webpage, video_id, fatal=False, default={})
         video_data.update(traverse_obj(next_data, ('props', 'pageProps', ('title', 'episode')), expected_type=dict)[0] or {})
         title = traverse_obj(video_data, 'headerTitle', 'episodeTitle')
         info = self._og_extract(webpage, require_title=not title)
@@ -323,7 +316,7 @@ class ITVIE(ITVBaseIE):
 
 class ITVBTCCIE(ITVBaseIE):
     _VALID_URL = r'https?://(?:www\.)?itv\.com/(?!(?:watch|hub)/)(?:[^/]+/)+(?P<id>[^/?#&]+)'
-    _IE_DESC = 'ITV articles: News, British Touring Car Championship'
+    IE_DESC = 'ITV articles: News, British Touring Car Championship'
     _TESTS = [{
         'note': 'British Touring Car Championship',
         'url': 'https://www.itv.com/btcc/articles/btcc-2018-all-the-action-from-brands-hatch',

youtube_dl/extractor/senateisvp.py

@@ -47,7 +47,7 @@ class SenateISVPIE(InfoExtractor):
         ['vetaff', '76462', 'http://vetaff-f.akamaihd.net'],
         ['arch', '', 'http://ussenate-f.akamaihd.net/']
     ]
-    _IE_NAME = 'senate.gov'
+    IE_NAME = 'senate.gov'
     _VALID_URL = r'https?://(?:www\.)?senate\.gov/isvp/?\?(?P<qs>.+)'
     _TESTS = [{
         'url': 'http://www.senate.gov/isvp/?comm=judiciary&type=live&stt=&filename=judiciary031715&auto_play=false&wmode=transparent&poster=http%3A%2F%2Fwww.judiciary.senate.gov%2Fthemes%2Fjudiciary%2Fimages%2Fvideo-poster-flash-fit.png',

youtube_dl/extractor/youtube.py

@@ -12,6 +12,7 @@ import re
 import string
 import time
 import traceback
+import math
 
 from .common import InfoExtractor, SearchInfoExtractor
 from ..compat import (
@@ -2528,6 +2529,58 @@ class YoutubeIE(YoutubeBaseInfoExtractor):
             if thumbnail:
                 thumbnails = [{'url': thumbnail}]
 
+        storyboards = []
+        sb_spec = try_get(player_response,
+                          lambda x: x['storyboards']['playerStoryboardSpecRenderer']['spec'],
+                          compat_str)
+        if sb_spec:
+            s_parts = sb_spec.split('|')
+            base_url = s_parts[0]
+            for i, params in enumerate(s_parts[1:]):
+                storyboard_attrib = params.split('#')
+                if len(storyboard_attrib) != 8:
+                    self._downloader.report_warning('Unable to extract storyboard')
+                    continue
+
+                frame_width = int_or_none(storyboard_attrib[0])
+                frame_height = int_or_none(storyboard_attrib[1])
+                total_frames = int_or_none(storyboard_attrib[2])
+                cols = int_or_none(storyboard_attrib[3])
+                rows = int_or_none(storyboard_attrib[4])
+                filename = storyboard_attrib[6]
+                sigh = storyboard_attrib[7]
+
+                if frame_width and frame_height and cols and rows and total_frames:
+                    frames = cols * rows
+                    width, height = frame_width * cols, frame_height * rows
+                    n_images = int(math.ceil(total_frames / float(cols * rows)))
+                else:
+                    self._downloader.report_warning('Unable to extract storyboard')
+                    continue
+
+                storyboards_url = base_url.replace('$L', compat_str(i)) + '&'
+                for j in range(n_images):
+                    url = storyboards_url.replace('$N', filename).replace('$M', compat_str(j)) + 'sigh=' + sigh
+                    if j == n_images - 1:
+                        remaining_frames = total_frames % (cols * rows)
+                        if remaining_frames != 0:
+                            frames = remaining_frames
+                            rows = int(math.ceil(float(remaining_frames) / rows))
+                            height = rows * frame_height
+                            if rows == 1:
+                                cols = remaining_frames
+                                width = cols * frame_width
+
+                    storyboards.append({
+                        'id': 'L{0}-M{1}'.format(i, j),
+                        'width': width,
+                        'height': height,
+                        'cols': cols,
+                        'rows': rows,
+                        'frames': frames,
+                        'url': url
+                    })
+
         category = microformat.get('category') or search_meta('genre')
         channel_id = self._extract_channel_id(
             webpage, videodetails=video_details, metadata=microformat)
@@ -2577,6 +2630,7 @@ class YoutubeIE(YoutubeBaseInfoExtractor):
             'categories': [category] if category else None,
             'tags': keywords,
             'is_live': is_live,
+            'storyboards': storyboards,
         }
 
         pctr = traverse_obj(

youtube_dl/jsinterp.py

@@ -686,6 +686,8 @@ class JSInterpreter(object):
             raise self.Exception('Cannot get index {idx!r:.100}'.format(**locals()), expr=repr(obj), cause=e)
 
     def _dump(self, obj, namespace):
+        if obj is JS_Undefined:
+            return 'undefined'
         try:
             return json.dumps(obj)
         except TypeError:

youtube_dl/options.py

@@ -789,6 +789,14 @@ def parseOpts(overrideArguments=None):
         '--list-thumbnails',
         action='store_true', dest='list_thumbnails', default=False,
         help='Simulate and list all available thumbnail formats')
+    thumbnail.add_option(
+        '--write-storyboards',
+        action='store_true', dest='writestoryboards', default=False,
+        help='Write all storyboards (grid of video frames) to disk')
+    thumbnail.add_option(
+        '--list-storyboards',
+        action='store_true', dest='list_storyboards', default=False,
+        help='Simulate and list all available storyboards')
 
     postproc = optparse.OptionGroup(parser, 'Post-processing Options')
     postproc.add_option(