{"record":{"id":"e5af6c014bbf1e75","repo":"ytdl-org/youtube-dl","slug":"cannot-download-embed-only-video-without-embedding","errorCode":null,"errorMessage":"Cannot download embed-only video without embedding URL. Please call youtube-dl with the URL of the page that embeds this video.","messagePattern":"Cannot download embed-only video without embedding URL\\. Please call youtube-dl with the URL of the page that embeds this video\\.","errorType":"exception","errorClass":"ExtractorError","httpStatus":403,"severity":"error","filePath":"youtube_dl/extractor/vimeo.py","lineNumber":668,"sourceCode":"        if is_pro:\n            # some videos require portfolio_id to be present in player url\n            # https://github.com/ytdl-org/youtube-dl/issues/20070\n            url = self._extract_url(url, self._download_webpage(url, video_id))\n            if not url:\n                url = 'https://vimeo.com/' + video_id\n        elif any(p in url for p in ('play_redirect_hls', 'moogaloop.swf')):\n            url = 'https://vimeo.com/' + video_id\n\n        try:\n            # Retrieve video webpage to extract further information\n            webpage, urlh = self._download_webpage_handle(\n                url, video_id, headers=headers)\n            redirect_url = urlh.geturl()\n        except ExtractorError as ee:\n            if isinstance(ee.cause, compat_HTTPError) and ee.cause.code == 403:\n                errmsg = ee.cause.read()\n                if b'Because of its privacy settings, this video cannot be played here' in errmsg:\n                    raise ExtractorError(\n                        'Cannot download embed-only video without embedding '\n                        'URL. Please call youtube-dl with the URL of the page '\n                        'that embeds this video.',\n                        expected=True)\n            raise\n\n        if '//player.vimeo.com/video/' in url:\n            config = self._search_json(\n                r'\\b(?:playerC|c)onfig\\s*=', webpage, 'info section', video_id)\n            if config.get('view') == 4:\n                config = self._verify_player_video_password(\n                    redirect_url, video_id, headers)\n            info = self._parse_config(config, video_id)\n            self._vimeo_sort_formats(info['formats'])\n            return info\n\n        if re.search(r'<form[^>]+?id=\"pw_form\"', webpage):\n            video_password = self._get_video_password()","sourceCodeStart":650,"sourceCodeEnd":686,"githubUrl":"https://github.com/ytdl-org/youtube-dl/blob/956b8c585591b401a543e409accb163eeaaa1193/youtube_dl/extractor/vimeo.py#L650-L686","documentation":"Raised by VimeoIE._real_extract when downloading the video page returns HTTP 403 whose body contains 'Because of its privacy settings, this video cannot be played here' — the mark of an embed-only (domain-restricted) video. The player refuses off-domain access, so the extractor needs the URL of the page that embeds the player, not the player/video URL alone. expected=True.","triggerScenarios":"Passing a player.vimeo.com/video/<id> URL (or moogaloop/play_redirect_hls variant) for a video whose privacy settings restrict playback to specific embed domains; the 403 body matches the marker string.","commonSituations":"Users copy the iframe src from devtools instead of the containing page; course/event sites that domain-lock their player; videos with 'hide from Vimeo' + domain-whitelist privacy.","solutions":["Call youtube-dl with the full URL of the page that embeds the video, not the player iframe URL.","If you only have the player URL, find the originating site (referrer, search the video id) and use that page's URL.","If you are the video owner, loosen privacy settings (allow embedding anywhere / public) to extract from vimeo.com directly.","As a last resort, authenticated session cookies for the allowed domain plus the page URL are required — there is no parameter to bypass domain restriction."],"exampleFix":"# before\nyoutube_dl 'https://player.vimeo.com/video/12345678'\n# after\nyoutube_dl 'https://example.com/course/lesson-1'   # page that embeds the player","handlingStrategy":"validation","validationCode":"if 'player.vimeo.com/video/' in url or 'moogaloop.swf' in url:\n    warn('embed-only risk: prefer the URL of the page embedding this player; domain-restricted videos 403 otherwise')","typeGuard":"def is_vimeo_player_url(u: str) -> bool:\n    \"\"\"True when u targets the Vimeo player directly and may hit embed-only privacy 403s.\"\"\"\n    return ('player.vimeo.com/video/' in u) or ('moogaloop.swf' in u) or ('play_redirect_hls' in u)","tryCatchPattern":"try:\n    ydl.extract_info(url)\nexcept ExtractorError as e:\n    if e.expected and 'embeds this video' in str(e):\n        resolve_containing_page_and_retry(url)  # swap in the embedding page's URL\n    else:\n        raise","preventionTips":["Never feed player.vimeo.com iframe src URLs to the extractor; use the embedding page's URL.","Detect player URLs upstream and map them back to their containing pages.","If you own the video, relax privacy settings to allow embedding anywhere."],"tags":["vimeo","privacy","embed-restriction","http-403","expected-error"],"backgroundTag":null,"analyzedSha":"956b8c585591b401a543e409accb163eeaaa1193","analyzedAt":"2026-08-14T18:59:47.863Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}