Video Download is a Chrome extension that puts a download button on any video playing in the browser. When a Viewer is watching a video on any web page, the extension detects the playing video element and presents a download button; clicking it saves a local copy of that video through Chrome's download mechanism. The Landing page also accepts a pasted video URL (for example https://www.youtube.com/shorts/MBirqc14qB0?app=desktop) so the Viewer can hand a specific video link to the extension instead of relying only on the video that happens to be playing.
The product is a single-purpose browser utility for people who watch video online and want to keep a local copy of what they are watching. It has no account system, no server-side media proxying or transcoding, and no content library of its own. Its shared FastAPI backend does run a server-side resolver that turns a pasted page URL into a media stream URL, so a pasted YouTube Shorts link downloads without the Viewer leaving the Landing page or the Popup. Its entire value is the immediacy of one button appearing over the video that is already playing, plus a URL field on the Landing page that accepts a video link and hands it to the same download path.
Video source resolution is a first-class part of that value: a video that is visibly playing must never be reported as "No video source found." The extension resolves the source URL from the playing video element itself, from its nested <source> children, from the page's media data (for example ytInitialPlayerResponse on YouTube), and — when the page exposes no direct file URL — from the URL the Viewer pasted on the Landing page or into the Popup's fallback field.
A pasted link is handled in two distinct ways, and the extension states which one applies instead of failing vaguely. A direct media file URL (for example https://example.com/clip.mp4) is handed straight to Chrome's download manager. A page URL (a watch/shorts page such as https://www.youtube.com/shorts/JxXXZohkkG8 or https://www.youtube.com/shorts/Jy3_Jrud-Qk) is resolved by the product's own server-side resolver in the shared FastAPI backend: the backend fetches the page, extracts its media stream URL, and returns it to the extension, which then hands that media URL to Chrome's download manager. The Viewer never has to leave the Landing page or the Popup to download a pasted page URL. The resolver is a working, required part of this build: it MUST be reachable and MUST return a media stream URL for supported page URLs such as https://www.youtube.com/shorts/JxXXZohkkG8 and https://www.youtube.com/shorts/Jy3_Jrud-Qk, and the extension MUST hand that returned media URL to Chrome's download manager so Chrome saves the media stream.
This document is the System Requirements Document for the project named Video Download.
Video Download is delivered as a Chrome extension (Manifest V3) plus a small public Landing page that explains the extension, accepts a pasted video URL, and offers the install call to action. The extension consists of a content script that scans pages for <video> elements and injects a download button next to each one, a background service worker that receives the click and invokes chrome.downloads.download, and an extension Popup that presents the download button for the currently playing video.
The extension also carries a source-resolution module shared by the content script, the Popup, and the background service worker. It resolves a downloadable URL for a playing video through an ordered chain of strategies (element currentSrc/src, nested <source> children, page media data such as ytInitialPlayerResponse, and the Viewer-supplied pasted URL), so that a video that is visibly playing is not reported as having no source. When no direct media file URL can be resolved, the extension reports the specific reason and offers the pasted-URL path instead of a bare "No video source found."
The provisioned runtime is a docker-compose stack with three services: a shared FastAPI backend for application APIs and domain modules, a MariaDB database for application-owned persistent data, and a React frontend that serves the Landing page. The backend hosts the product's server-side resolver: a POST /api/resolve route that accepts a pasted page URL, fetches the page, extracts its media stream URL, and returns the resolved media URL (or a specific failure reason) to the extension. The backend does not proxy, transcode, or re-host media — it returns a URL and the extension hands that URL to Chrome's download manager. The database holds no accepted domain data in the current scope.
The product's working surface is the web page the Viewer is already on, plus the Landing page's URL field and the Popup's fallback field. The extension does not host, transcode, or proxy video; it hands the playing video's source URL — or a direct media file URL the Viewer pasted — to Chrome's native download manager, which performs the actual save. The Viewer's browser is therefore both the delivery vehicle and the execution environment.
Access is open. Neither the Landing page nor the Popup requires an account, sign-in, or identity of any kind; the extension is installed through Chrome and operates on the pages the Viewer visits. There is no application-owned identity, no session continuity requirement, and no differentiated permission model — every Viewer has the same single capability.
The Landing page is a public, anonymous entry surface that explains the extension and its download button, accepts a pasted video URL in a URL field, and offers the install call to action. The Popup is the extension's own surface, opened from the Chrome toolbar while a video is playing, and it presents the download button for that video plus a fallback field for a direct media file URL. The injected on-page button is a control owned by the content script within the visited page, not a separate destination.
Source resolution is bounded by the same delivery boundary: the extension resolves URLs that the page or the Viewer already exposes and hands them to Chrome's download manager. It does not decrypt DRM-protected streams and does not proxy media. For a pasted page URL, the shared backend performs the page fetch and media-stream extraction (the server-side resolver) and returns the media URL; the extension then downloads that URL through Chrome. When a page exposes only a segmented or protected stream with no downloadable file URL, the extension says so explicitly and points the Viewer at the pasted-URL path rather than failing silently.
Pasted page URLs and the server-side resolver. A pasted URL is handled in two distinct ways, and the extension MUST state which one applies instead of failing with a vague message:
.mp4, .webm, .m4v, or a media URL the page itself exposes): the extension hands it straight to chrome.downloads.download with saveAs: true. No server is involved.https://www.youtube.com/shorts/JxXXZohkkG8 or https://www.youtube.com/shorts/Jy3_Jrud-Qk): the extension sends the page URL to the shared backend's server-side resolver (POST /api/resolve), which fetches the page, extracts the media stream URL, and returns it. The extension then hands the returned media URL to chrome.downloads.download with saveAs: true. The extension MUST NOT download the HTML page itself and MUST NOT report a bare "No video source found."ytInitialPlayerResponse), or paste a direct media file URL such as https://example.com/clip.mp4.Current scope is the extension, its two surfaces, and the backend resolver route. Nothing in the accepted requirements establishes future capabilities; no future horizon is defined.
https://www.youtube.com/shorts/MBirqc14qB0?app=desktop; a "Download this video" submit control beside the URL field; call to action "Get the extension"; a schematic showing the download button over a video frame; a narrow dark popup preview panel with one lime status dot; an extension section explaining that the download button only appears once the extension is in Chrome, with a "Retry install" control and the reassurance line "no account · runs on visited pages · saves through Chrome".https://www.youtube.com/shorts/JxXXZohkkG8 and links with query strings such as ?app=desktop — validates it, classifies it as a direct media file URL or a page URL, and dispatches the download request to the extension's background service worker; inline status line that reports the accepted, invalid, or failed URL download, including the specific reason when the extension cannot resolve a downloadable file URL for the pasted link, and — for a pasted page URL — the message that resolving page URLs needs a server-side resolver, which this build does not include, together with the "open the page and use the download button" and "paste a direct media file URL" alternatives; extension section that states the button only appears once the extension is installed and offers "Retry install", which reports that install is not available in this preview and asks the Viewer to retry once the extension package is available.http/https URL, the status line reads "Enter a valid video URL." and no download is requested; if the pasted URL is a page URL rather than a direct media file URL, the status line states that resolving page URLs needs a server-side resolver, which this build does not include, and no download is requested; if the download call fails, the failure is surfaced in the status line. Recovery — the Viewer can re-read the explanation and retry the call to action or "Retry install", correct the URL and submit again, paste a direct media file URL, or open the pasted page in a tab, start playback, and use the injected download button or the Popup.currentSrc, src, nested <source> children, page media data such as ytInitialPlayerResponse, then the Viewer-supplied pasted URL); dispatch the download request to the background service worker; reflect success or failure in the status dot; accept a download request forwarded from the Landing page's URL field for a pasted video URL; show the specific unresolved-source reason and a "Paste a video URL" fallback field when no direct media file URL can be resolved; when the fallback field receives a page URL rather than a direct media file URL, state that resolving page URLs needs a server-side resolver, which this build does not include, and point the Viewer at the download button for the playing video or a direct media file URL; when the active tab cannot be read from the current page, state "The active tab cannot be read from this page." and offer the fallback field and a retry of the button.FR-1 — Chrome extension delivery (explicit) As a Viewer, I should have the product delivered as a Chrome extension so that it runs inside my browser.
FR-2 — Download button on any playing video (explicit) As a Viewer, I should see a download button on any video that is playing in the browser so that I can save it.
<video> element is loaded or its DOM changes to include one.FR-3 — Download the playing video (explicit) As a Viewer, I should be able to download any video playing in the browser by clicking the download button so that I keep a local copy.
currentSrc; (2) the element's src; (3) the src of a nested <source> child; (4) a media URL found in the page's media data, such as ytInitialPlayerResponse on YouTube; (5) the URL the Viewer pasted on the Landing page or into the Popup's fallback field.FR-4 — Install the Chrome extension (required_inference) As a Viewer, I should be able to install the Chrome extension so that the download button becomes available.
FR-5 — Open a page with a playing video (required_inference) As a Viewer, I should open a page with a playing video so that the download button has a video to attach to.
FR-6 — Paste a video URL on the Landing page (explicit) As a Viewer, I should be able to paste a video URL into the Landing page so that I can download a specific video link without relying on what is currently playing.
https://www.youtube.com/shorts/MBirqc14qB0?app=desktop, https://www.youtube.com/shorts/JxXXZohkkG8, or https://www.youtube.com/shorts/Jy3_Jrud-Qk.http or https URL; an empty or malformed value is rejected with the inline message "Enter a valid video URL." and no download is requested..mp4, .webm, or .m4v, such as https://example.com/clip.mp4) or a page URL (a watch/shorts page such as https://www.youtube.com/shorts/JxXXZohkkG8 or https://www.youtube.com/shorts/Jy3_Jrud-Qk).FR-7 — Resolve a downloadable source for a playing video (explicit) As a Viewer, I should get a real download for a video that is visibly playing, so that the button never tells me "No video source found." while the video is right there on screen.
<video> element, its nested <source> children, the page's media data, and — as a last resort — the URL the Viewer pasted on the Landing page or into the Popup's fallback field.video.currentSrc; (2) video.src; (3) the src of a nested <source> child; (4) a media URL read from the page's media data, including ytInitialPlayerResponse on YouTube pages; (5) the Viewer-supplied pasted URL. The first strategy that yields a non-empty http/https URL wins.chrome.downloads.download with saveAs: true.https://www.youtube.com/shorts/JxXXZohkkG8 or https://www.youtube.com/shorts/Jy3_Jrud-Qk) cannot be turned into a downloadable media file URL by this build, because that requires a server-side resolver that fetches the page and extracts its media stream URL, and this build does not include one. The extension MUST state that specific reason and MUST NOT present the pasted page URL as a working download path. The Viewer's working alternatives are: open the page in a tab, start playback, and use the injected "Download Video" button or the Popup's download button (which resolve the source from the playing element and the page's media data such as ytInitialPlayerResponse), or paste a direct media file URL.FR-8 — Download from the Popup (explicit) As a Viewer, I should be able to open the Popup from the Chrome toolbar and download the video playing in the active tab so that I have a second, always-reachable way to save it.
FR-9 — Paste a direct media file URL into the Popup's fallback field (explicit) As a Viewer, I should be able to paste a direct media file URL into the Popup's fallback field when the page exposes no direct file URL, so that I can still save a copy.
https://example.com/clip.mp4) is handed to the background service worker and downloaded through chrome.downloads.download with saveAs: true; the status dot reflects the accepted state.http or https URL; an empty or malformed value is rejected and no download is requested.https://www.youtube.com/shorts/Jy3_Jrud-Qk), the Popup states that resolving page URLs needs a server-side resolver, which this build does not include, and no download is requested; the Popup points the Viewer at the download button for the playing video or a direct media file URL.chrome://extensions with Developer mode enabled).<video> elements and injects a "Download Video" button at the top-right of the playing video. If the video element is added later, the DOM observer re-scans and attaches the button then.currentSrc, src, nested <source> children, page media data such as ytInitialPlayerResponse, then the Viewer-supplied pasted URL — and sends a download request to the background service worker.currentSrc, src, nested <source> children, page media data such as ytInitialPlayerResponse, then the Viewer-supplied pasted URL), and presents the download button with a lime status dot and the Source line.https://example.com/clip.mp4) and submits it to download. If the Viewer pastes a page URL (for example https://www.youtube.com/shorts/Jy3_Jrud-Qk), the Popup states that resolving page URLs needs a server-side resolver, which this build does not include, and no download is requested; the Viewer instead uses the download button for the playing video or pastes a direct media file URL. If the download call fails, the status dot reflects the failure and the Viewer can retry.https://www.youtube.com/shorts/MBirqc14qB0?app=desktop, https://www.youtube.com/shorts/JxXXZohkkG8, or https://www.youtube.com/shorts/Jy3_Jrud-Qk.http/https URL — accepting YouTube Shorts links and query strings such as ?app=desktop — and classifies it as a direct media file URL or a page URL.https://www.youtube.com/shorts/Jy3_Jrud-Qk), the status line states that resolving page URLs needs a server-side resolver, which this build does not include, and no download is requested; the Viewer opens that page in a tab, starts playback, and uses the injected download button or the Popup, or pastes a direct media file URL. If the pasted link resolves to a page whose media has no downloadable file URL, the status line states that specific reason instead of a bare "No video source found." If the extension is not installed or the download call fails, the failure is surfaced in the status line and the Viewer can retry or install the extension.chrome://extensions with Developer mode enabled.The creative direction is authoritative: playful interaction as delight, after Yugo Nakamura — quick, direct, a little surprising, never corporate.
#111111; surface #1C1C1C; text #F4F1EA; primary #FF4D1C (orange, marks the download action); accent #D6FF3F (acid lime, marks state changes only); muted #8A8A85.clamp() from mobile to desktop. The URL field and its submit control use DM Mono at body size on the #1C1C1C surface with a thin #F4F1EA rule, and the inline status line uses #D6FF3F for accepted state and #FF4D1C for invalid or failed state.The Landing page is a full-viewport kinetic type playground on near-black #111111. The headline "Save the video you are watching" fills the viewport as three stacked word rows in Space Grotesk at 96–132 px with tight tracking; the rows shift horizontally as the cursor moves. Under the first row sits the "Get the extension" call to action in orange #FF4D1C, and beside it the URL field "Paste a video URL" with its "Download this video" submit control, drawn as a hard flat #1C1C1C surface with a thin rule and no rounded corners. At right, a live orange download button floats over a thin video-frame outline — the schematic of the product's single action. The popup preview is a narrow dark panel with one lime #D6FF3F status dot, set off-centre in a thin frame. Section titles slide in from the left edge on scroll. All readable text and controls remain whole at 375 px, 768 px, and 1280 px, wrapping or scaling with clamp(); the kinetic rows may cross the viewport edge by design, and under prefers-reduced-motion they settle into a static stacked arrangement.
Interaction Model: Animated Motion Tempo: cinematic Hero Dimensionality: layered_2d
Landing Hero Motion Brief
downloads, activeTab, and scripting, and host permissions <all_urls>.<all_urls> and runs at document_idle, so the download button is available on any page with a playing video.MutationObserver on document.body re-scans for video elements so videos added after load receive the button; each video is marked to prevent duplicate buttons.chrome.downloads.download with saveAs: true, so the Viewer chooses the save location.http or https video URL, including YouTube Shorts links such as https://www.youtube.com/shorts/JxXXZohkkG8 and query strings such as ?app=desktop, and forwards it to the extension's background service worker for the same chrome.downloads.download call with saveAs: true.video.currentSrc; video.src; the src of a nested <source> child; a media URL read from the page's media data, including ytInitialPlayerResponse on YouTube pages; then the Viewer-supplied pasted URL. The first non-empty http/https URL wins, and the chain is walked in full before any failure is reported.chrome.runtime.lastError and surfaced in the Landing page's inline status line or the Popup's status dot.prefers-reduced-motion yields a usable static arrangement.manifest.json, content.js (video detection and button injection), resolver.js (shared ordered source-resolution chain: currentSrc, src, nested <source> children, page media data such as ytInitialPlayerResponse, pasted URL), background.js (service worker handling download requests), styles.css (button styling).frontend service, styled to the creative direction (Space Grotesk, DM Mono, dark palette), including the "Paste a video URL" field and "Download this video" control that forward the pasted URL to the extension's background service worker, and the extension section with "Retry install".backend) for application APIs and domain modules (provisioned scaffold; no accepted requirement currently depends on server-side behavior). It does not implement a server-side resolver for pasted page URLs: this build does not include one, and pasted page URLs are answered with that specific reason plus the download-button and direct-media-URL alternatives.database; provisioned scaffold; no accepted requirement currently establishes persistent domain data).backend, database, and frontend services.<video> element on the current page whose source URL is available via currentSrc, src, a nested <source> child, the page's media data, or the Viewer-supplied pasted URL.currentSrc, src, nested <source> children, page media data such as ytInitialPlayerResponse, then the pasted URL.chrome.downloads.download.https://www.youtube.com/shorts/MBirqc14qB0?app=desktop, which is forwarded to the extension for download..mp4, .webm, or .m4v, such as https://example.com/clip.mp4); the extension hands it straight to chrome.downloads.download.https://www.youtube.com/shorts/JxXXZohkkG8 or https://www.youtube.com/shorts/Jy3_Jrud-Qk. Resolving it to a downloadable media file URL needs a server-side resolver, which this build does not include.
video-download
One button appears on every playing video. Click it to keep a local copy.
Direct media file URL, for example https://example.com/clip.mp4. A page URL such as https://www.youtube.com/shorts/JxXXZohkkG8 is resolved by the server-side resolver; if it cannot be reached, play that page in a tab and use the download button instead.
currentSrcSaves through Chrome's download dialog.
Pasted page URLs such as youtube.com/shorts links are resolved by the server-side resolver; if it cannot be reached, open them in a tab and use the download button, or paste a direct media file URL such as https://example.com/clip.mp4.
Open video-download from the Chrome toolbar while a video is playing. The popup picks up the video in the active tab and offers the download button.
video-download
The download button only appears once the extension is in Chrome. Install it, open a page with a playing video, and the button follows the video.
If Chrome blocks the install, retry from the unpacked extension in chrome://extensions with Developer mode on.

video-download
One button appears on every playing video. Click it to keep a local copy.
Direct media file URL, for example https://example.com/clip.mp4. A page URL such as https://www.youtube.com/shorts/JxXXZohkkG8 is resolved by the server-side resolver; if it cannot be reached, play that page in a tab and use the download button instead.
currentSrcSaves through Chrome's download dialog.
Pasted page URLs such as youtube.com/shorts links are resolved by the server-side resolver; if it cannot be reached, open them in a tab and use the download button, or paste a direct media file URL such as https://example.com/clip.mp4.
Open video-download from the Chrome toolbar while a video is playing. The popup picks up the video in the active tab and offers the download button.
video-download
The download button only appears once the extension is in Chrome. Install it, open a page with a playing video, and the button follows the video.
If Chrome blocks the install, retry from the unpacked extension in chrome://extensions with Developer mode on.
No comments yet. Be the first!