gopeed-extension-youtube: adding YouTube to the Gopeed download manager

What the extension adds to Gopeed

This is a Gopeed extension for YouTube. The project description calls it the YouTube video download extension of gopeed, and the README states the job plainly: download YouTube videos and playlists with Gopeed.

Gopeed is a download manager, so the value proposition is consolidation rather than new capability. If you already run Gopeed for HTTP downloads, adding this extension means YouTube goes into the same task list, with the same queue, the same pause and resume, and the same download history, instead of living in a separate tool with its own command line and its own output directory.

The requirement is explicit: it requires Gopeed version 2.0.0 or newer. Since extensions are loaded by the host application through its own extension page, that version floor is about the host, not about Node.

The documented features are six. Regular videos and Shorts are supported. Playlists can be loaded and the videos you want can be selected from them. Download resolution goes up to 8K when the source video has it. Audio and video tracks are merged automatically into a single MP4 by FFmpeg with no manual step. You can choose a preferred resolution, or select Best for the highest available quality.

The users are Gopeed users who want YouTube in the same workflow, and the dependency on FFmpeg for the merge step is the one external requirement worth noting before you install anything.

Installing through the Gopeed extension page

Installation happens inside Gopeed, not through a package manager.

The documented procedure is to open the Gopeed extension page, enter the repository address https://github.com/monkeyWie/gopeed-extension-youtube, and click install. There is an animated image in the documentation showing the step.

That design follows from how Gopeed extensions work. The project links its own developer documentation, How to develop a gopeed extension, and points at the YouTube.js project as a useful reference. In other words, the extension is loaded by the host application from a source address, which is why the install step is a paste rather than a command.

The repository tree shows what is involved. There is a manifest.json, which is the extension descriptor the host reads, a src/ directory with the extension source, a dist/ directory holding the built bundle, a test/ directory, an icon.png, and the build configuration: babel.config.js, webpack.config.js, a .eslintrc and a .prettierrc.

The package manifest is marked private with the name gopeed-extension-youtube and the version 1.0.0, so it is not published to a registry. The entry point is index.js, the module type is esm, and the build is a webpack bundle rather than a plain script, which is why the dist/ directory is part of the tree.

Creating a task from a YouTube URL

Using the extension means using Gopeed's own task panel. You open the Create Task panel, paste a YouTube URL, and click Download.

Three URL shapes are supported, and the documentation gives the pattern for each with a placeholder to replace with the identifiers from a real link:

| Type | Example URL | | --- | --- | | Video | `https://www.youtube.com/watch?v=VIDEO_ID` | | Playlist | `https://www.youtube.com/playlist?list=PLAYLIST_ID` | | Shorts | `https://www.youtube.com/shorts/VIDEO_ID` |

The playlist behaviour has a specific rule that is easy to get wrong. For a playlist, you paste the playlist URL to load its available videos, then select the entries you want to download. A video link downloads only the current video, even when it was opened from a playlist. So the two URLs are not interchangeable, and pasting an individual video link from inside a playlist gives you one file rather than the list.

Quality is set in the extension settings, where you choose your preferred resolution. There is a Fallback to Best Quality option, and enabling it uses the highest available quality when your preferred resolution is unavailable. That option is the difference between a download that fails on a video published at a lower resolution and one that gives you what exists.

The PO Token wait that looks like a hang

There is one behaviour in the documentation that deserves its own attention, because it looks like a bug and is not.

The note says that after you start a download, the speed may stay at zero for a while before data begins downloading, and that this is normal: the extension needs to complete YouTube's PO Token verification first. The download will begin automatically once verification is complete.

So the symptom is a task sitting at zero bytes per second, with no progress bar, and the cause is an authentication step against YouTube rather than a stalled transfer. If you cancel a task during that window because it looks hung, you will conclude the extension does not work when it does.

This is also the structural difference between this extension and a command line downloader such as youtube-dl or yt-dlp, and it is the honest boundary of what the project does. Those tools generate their own request signatures and tokens as part of a process they control. A browser extension running inside a page has the session and the request context of a real browser, and YouTube asks it to prove that context. The trade is convenience and integration for Gopeed users against a dependence on an external verification step that the user can only wait out.

How the extension is built and tested

The dependency list in the package manifest explains most of the implementation.

The runtime dependencies are youtubei.js at ^18.0.0, which is the YouTube.js library the documentation points at, googlevideo at ^4.0.4, which is the protocol client used to talk to the media stream endpoints, bgutils-js at ^4.0.3, and @ungap/structured-clone at ^1.4.0, which is there because the extension runs in a browser context where the structured clone algorithm is not always available as expected.

The build tooling is webpack at ^5.75.0 with webpack-cli, babel-loader and @babel/core with the preset-env, plus clean-webpack-plugin. The gopeed package at ^1.3.6 and the gopeed-polyfill-webpack-plugin at ^1.0.6 are development dependencies, which tells you the polyfill plugin exists to shim the host environment during the bundle build.

The three package scripts are the whole build story:

  "scripts": {
    "test": "node --test test/*.test.js",
    "dev": "webpack --mode development --watch",
    "build": "webpack --mode production"
  },

Tests run on the Node test runner with no test framework dependency, which keeps the dependency list short. The dev script is a watch build and the build script is the production bundle that ends up in dist/.

The manifest also declares a licence field of ISC for the package, and the repository metadata does not record a licence for the project, so the licensing position is worth checking in the repository before you redistribute anything.

Where this extension is the wrong tool

The first limit is that it is a browser extension, not a library and not a service. It runs inside Gopeed, which is a desktop application, so there is no headless mode, no API and no server side story. A scheduled pipeline that fetches a playlist on a cron job has nothing to drive here.

The second is the dependency on YouTube's own behaviour. The extension depends on youtubei.js and googlevideo tracking YouTube's internal protocols, and YouTube changes those. The repository publishes no GitHub releases and the last push was on 2026-09-19, so there is no version stream to track and no changelog to consult when a download stops working. You find out that something broke, and then you wait for a fix.

The third is the merge step. The audio and video tracks are combined by FFmpeg into a single MP4, which means FFmpeg has to be present and reachable. The documentation lists it as a feature rather than as a prerequisite, so it is worth checking what happens on a machine without it before you rely on the output.

The fourth is what a downloader is for. Downloading a video from a platform is only legitimate when you have the right to do so, whether that is your own content, a licence, or a public domain work, and the extension offers no way to check that. That is a decision for the user of the tool, not something the software can decide.

Compare that with a dedicated command line downloader. The difference in approach is that a standalone tool runs headless, can be scripted and scheduled, and prints structured output, while this extension trades that for a native place in the Gopeed interface and for the browser session context that the PO Token flow needs. If you want a script, the extension is the wrong shape. If you want the video next to your other downloads with a progress bar you can watch, it is exactly right.

Licence, maintenance and what to check before installing

The package manifest declares a licence field of ISC, and the repository metadata does not record a licence for the project, so there is no clearly stated licence text to point at. The documentation points to the Gopeed extension development page and to YouTube.js, and both are more useful for understanding the mechanics than the README is.

On maintenance, the repository is not archived and the last push was on 2026-09-19, so the code is roughly a month old relative to today. The package version is 1.0.0 and there are no GitHub releases, so version tracking is by the package manifest rather than by tags. The repository topics list gopeed-extension, youtube, youtube-dl and youtube-downloader, which places it in the same category as the command line tools even though the mechanism is completely different.

What to verify before you install is short. Confirm you are on Gopeed 2.0.0 or newer, because the extension will not load otherwise. Confirm FFmpeg is available, since it does the track merging. Then try one video before you try a playlist, so that any failure is a single simple case, and let the PO Token phase run to completion rather than cancelling a task that looks stalled.

For a long playlist, check the quality fallback setting before you start, because the alternative is a batch of downloads at a resolution you did not ask for.

Editorial conclusion

This extension suits someone who already uses Gopeed as their download manager and wants YouTube handled inside the same task list, without running a separate command line downloader alongside it. It does not suit a server side pipeline, because it is a browser extension that depends on Gopeed running and on YouTube's PO Token verification, and it does not do anything for a user who has no Gopeed installation. Before you rely on it, read the PO Token note in the documentation, because the zero speed phase before a download starts is expected behaviour rather than a fault, and check the resolution fallback setting if your preferred quality is often unavailable.

Frequently asked questions

Official sources

1. Issues
2. monkeyWie/gopeed-extension-youtube on GitHub
3. README