ytdlp2STRM
Prerequisite
- Python 3 https://www.python.org/downloads/
- Tested with Python 3.10 and 3.11. Very new major/minor releases occasionally ship breaking changes against some of the Python dependencies; if you hit unexplained import or runtime errors, try Python 3.11.
- On Windows make sure “Add Python to PATH” is checked during install.
- FFmpeg https://ffmpeg.org/ — must be available on the system
PATH (ffmpeg -version from a terminal should work).
- yt-dlp https://github.com/yt-dlp/yt-dlp — must be available on the system
PATH as a binary (yt-dlp --version must work from a terminal), because ytdlp2STRM calls it as an external process.
pip install -r requierments.txt installs the Python package, but on some systems the entry-point binary is not picked up on PATH. If that happens, install it as a binary instead:
- Windows (PowerShell):
winget install yt-dlp.yt-dlp
- Linux (Debian/Ubuntu):
sudo apt install yt-dlp or grab the release binary from the yt-dlp repo.
- macOS:
brew install yt-dlp.
Installation and usage
- To allocate ytdlp2STRM, I suggest using /opt/ in Linux or C:\ProgramData in Windows.
Linux
- The next steps have been tested on Ubuntu 22.04 LTS. In terminal:
cd /opt && git clone https://github.com/fe80Grau/ytdlp2STRM.git
cd /opt/ytdlp2STRM && pip install -r requierments.txt
- Copy service file to system services folder
sudo cp config/ytdlp2strm.service /etc/systemd/system/ytdlp2strm.service
sudo systemctl enable ytdlp2strm.service
sudo systemctl start ytdlp2strm.service
sudo systemctl status ytdlp2strm.service
http://localhost:5000/
Windows
Use PowerShell. Choose one explicit Python interpreter and use it both for installing dependencies and for the scheduled task; a task may have a different PATH from your terminal. Python 3.10/3.11 are the tested versions. Keep FFmpeg and yt-dlp available to the task’s account as well.
cd C:\ProgramData
git clone https://github.com/fe80Grau/ytdlp2STRM.git
$ProjectPath = 'C:\ProgramData\ytdlp2STRM'
# Replace this example with the full path to your python.exe (or venv python.exe).
$PythonExe = 'C:\Python311\python.exe'
Set-Location -LiteralPath $ProjectPath
& $PythonExe -m pip install -r ./requierments.txt
& $PythonExe -m pip check
First check startup in the foreground
Run this before creating a task, so missing dependencies, invalid configuration, permissions or port conflicts are visible. This starts the real application and its configured cron jobs. Stop it with Ctrl+C before starting a second instance.
Set-Location -LiteralPath $ProjectPath
& $PythonExe -u .\main.py
Open http://localhost:5000/ (or the host/port configured in config/config.json). If startup fails here, fix the displayed error first; creating a task will not fix an import/configuration error.
Recommended: current-user task at sign-in
The optional helper creates a sign-in task for the current Windows user, with no stored password and no automatic privilege elevation. It does not start the application. Sign-in is intentional: an interactive user token cannot run before that user logs in. Use the same Windows account that passed the foreground check.
Preview and validate without registering a task or writing files (no Administrator session needed):
.\scripts\install-windows-task.ps1 -ProjectPath $ProjectPath -PythonExe $PythonExe -WhatIf
# -DryRun is equivalent. Both return the generated XML; neither starts main.py.
After reviewing the XML, register and start it explicitly:
.\scripts\install-windows-task.ps1 -ProjectPath $ProjectPath -PythonExe $PythonExe
Start-ScheduledTask -TaskName 'ytdlp2STRM' -TaskPath '\'
The helper requires absolute local paths, supports spaces, and refuses to replace an existing task. For an existing installation, review/edit that task in Task Scheduler instead of creating a second running instance. If PowerShell blocks the script, review it and use a process-only execution-policy exception according to your local policy; do not disable execution policy machine-wide.
Alternative: manual import / boot-time task
config/MS-TASK-ytdlp2STRM.xml remains a boot-trigger template. Before importing, edit its Command (if Windows is not in C:\Windows), Arguments (both the project/launcher path and the absolute Python path), and WorkingDirectory. The example Python path is not auto-detected. The launcher is scripts/start-windows.cmd; it changes to its own project directory, uses python.exe -u, appends stdout and stderr to <project>\log.txt, and preserves Python’s exit code.
# From an elevated terminal, after reviewing/editing the template:
schtasks.exe /create /tn 'ytdlp2STRM' /xml "$ProjectPath\config\MS-TASK-ytdlp2STRM.xml"
For unattended startup before sign-in, also configure the task’s General tab with an appropriate account and “Run whether user is logged on or not”; supply any required credentials through Task Scheduler, not a script. Confirm that account can run the selected Python, read/write the project/media folders, and access required executables and network resources. Do not switch to SYSTEM or “highest privileges” just to hide a permissions error. An interactive-account boot trigger alone does not provide unattended startup.
If the task returns to Ready or localhost is unavailable
Ready means the task is not currently running, not that the web server started successfully. A successful /run or Start-ScheduledTask only submits the start request. Inspect the exact task, its exit result and both output streams:
Get-ScheduledTask -TaskName 'ytdlp2STRM' -TaskPath '\' |
Select-Object TaskName, State
Get-ScheduledTaskInfo -TaskName 'ytdlp2STRM' -TaskPath '\' |
Select-Object LastRunTime, LastTaskResult
Get-Content -LiteralPath "$ProjectPath\log.txt" -Tail 100
# Inspect the executable, arguments, directory and execution account:
(Get-ScheduledTask -TaskName 'ytdlp2STRM' -TaskPath '\').Actions
(Get-ScheduledTask -TaskName 'ytdlp2STRM' -TaskPath '\').Principal
The former action /c python main.py > log.txt depended on PATH, buffered stdout and discarded stderr from the log. An empty log therefore did not rule out a Python/import error. The launcher now appends startup/exit markers and exception tracebacks; log.txt grows until you archive/truncate it while the task is stopped. If no log is created, check the action paths, account permissions and Task Scheduler History/Operational log, then repeat the foreground command under the task’s account. Running alone is not an HTTP health check: verify the configured URL too. Do not assume a firewall problem before confirming the server actually started.
Docker
To deploy this as a Docker container, follow these steps in the ytdlp2STRM root folder.
- Build Docker image. The default host port is 5005, to change it edit Dockerfile and change the env value of DOCKER_PORT with the same port that you will configure in the docker run command.
docker build . -t "ytdlp2strm"
- Create a volume to preserve data.
docker create --name ytdlp2strm-data ytdlp2strm
- Run the container with volume and mount D:\media (host folder for accessing strm files, change it as you prefer) in /media (container folder).
docker run -p 5005:5000 --restart=always -d -v D:\media:/media --volumes-from ytdlp2strm-data --name ytdlp2STRM ytdlp2strm
- Check the GUI in the browser
http://localhost:5005/
Docker HUB
http://localhost:5001/
Docker compose YAML template
- Thank you INPoppoRTUNE
- INPoppoRTUNE was here
---
services:
ytdlp2strm:
image: fe80grau/ytdlp2strm
container_name: ytdlp2STRM
environment:
- AM_I_IN_A_DOCKER_CONTAINER=Yes
- DOCKER_PORT=5005
volumes:
- /local/path/to/media:/media
- /local/path/to/channel_list.json:/opt/ytdlp2STRM/plugins/youtube/channel_list.json
- /local/path/to/yt_config.json:/opt/ytdlp2STRM/plugins/youtube/config.json
- /local/path/to/config.json:/opt/ytdlp2STRM/config/config.json
- /local/path/to/crons.json:/opt/ytdlp2STRM/config/crons.json
- ytdlp2strm-data:/opt/ytdlp2STRM
ports:
- 5005:5000
restart: always
volumes:
ytdlp2strm-data:
Where:
/local/path/to/media is the local folder where the .strm file will be created/local/path/to/config.json is optional and will set your ytdlp2STRM general settings; formatted as config.example.json/local/path/to/crons.json is optional and will set your ytdlp2STRM cronjob settings; formatted as crons.example.json/local/path/to/channel_list.json is optional and will set your Youtube channel list; formatted as channel_list.example.json/local/path/to/yt_config.json is optional and will set your Youtube plugin settings; formatted as config.example.json
- The default env value of DOCKER_PORT is 5005, make sure to put 5005 as host port or re-declare the env value of DOCKER_PORT
Additional info
- After that you can view all channels folders within /media/Youtube and their strm files. If you are using Jellyfin/Emby, add /media/Youtube, /media/Twitch
and /media/Crunchyroll as folders in Library and enjoy it!
New in v1.1.3
- Fix: Jellyfin daemon started even when
jellyfin_preload was "False": the Crunchyroll plugin used bool(config['jellyfin_preload']), but bool("False") returns True in Python (any non-empty string is truthy). This caused the Jellyfin preload daemon to run and spam HTTP errors every minute even with the feature disabled. The check now uses str(value).lower() == 'true', matching the rest of the codebase.
New in v1.1.2
- Security hardening (Issue #122):
- Argument injection protection: plugin streaming routes (
/youtube/direct/<id>, /twitch/bridge/<id>, etc.) now validate the media ID against an allowlist ([A-Za-z0-9_.-], no leading -) before passing it to yt-dlp, returning HTTP 400 on invalid input.
- Replaced
eval() in cli.py: plugin method resolution now uses getattr instead of eval() on user-supplied strings, preventing code injection.
- Host binding now respects
ytdlp2strm_host: main.py reads ytdlp2strm_host from config.json instead of hardcoding 0.0.0.0. The default config now ships with 127.0.0.1, reducing accidental exposure of the admin UI to the network.
- Optional HTTP Basic Auth for admin routes: setting
ytdlp2strm_web_username and ytdlp2strm_web_password in config.json protects the dashboard (/, /general, /plugin, /crons, /log, /restart_service) while leaving streaming endpoints open for Jellyfin/Emby/Kodi. Streaming routes (/youtube/*, /twitch/*, etc.) remain unauthenticated so players keep working.
New in v1.1.1
New in v1.1.0
- Season folders by year: YouTube and Twitch videos are now organized in year-based Season folders
- Structure:
Channel/Season {year}/S{year}E{XX} - video.strm
- Example:
Channel [ID]/Season 2025/S2025E01 - Video Title.strm
- UI improvements:
- Authentication improvements:
- All yt-dlp commands now properly use cookie authentication
- Better handling of subscriber-only content on Twitch
Youtube
- SponsorBlock doesn’t work in redirect mode.
- Local NFO for each video
- audio- prefix
- Season folders by year: Videos are organized in
Season {year} folders (e.g., Season 2025, Season 2026)
- Episode numbering: Files are named
S{year}E{XX} format, resetting to E01 each year
- Cookie authentication: Supports both browser cookies and cookie files for age-restricted content
- Language configuration: Configurable audio language via
lang parameter in config.json
- Video quality limit:
video_quality can limit playback quality. Use best for the current behavior or values like 1080, 720, 480 to avoid selecting higher resolutions.
- Subtitles: When
download_subtitles is enabled, YouTube .vtt subtitles are downloaded next to each .strm file. WebVTT files are post-processed to improve Jellyfin/Emby rendering:
- Force centered subtitle alignment.
- Remove YouTube karaoke inline timestamps.
- Collapse repeated rollup/persiana cues.
- The same cleanup is also applied when subtitles are served through
/youtube/subtitles/<id>.vtt.
convert_subtitles_to_srt can also create .srt sidecar files from the cleaned VTT subtitles for better compatibility with Android/TV clients.keep_vtt_subtitles keeps the original cleaned .vtt files when SRT conversion is enabled.
- Direct playback cache: YouTube direct mode resolves the best HLS stream and stores the processed manifest in
<strm_output_folder>/.direct_cache.
direct_stream_cache_hours controls how long cached direct manifests are considered valid.- Cached manifests avoid repeating the slow
yt-dlp resolution on repeated playback.
- Optimized direct HLS: With
direct_serve_media_playlist enabled, ytdlp2STRM serves the selected media playlist directly instead of the full master playlist, reducing startup work for Jellyfin/Emby while keeping the selected highest-quality stream.
- The generated VOD playlist is cacheable for
direct_stream_cache_hours, which can reduce extra playlist reloads during seek operations.
- Seeking still depends on Jellyfin/Emby fetching the target YouTube HLS segment from
googlevideo.com. For near-instant seeking like YouTube, the only fully reliable options are local/download playback or a future segment proxy/cache mode, both with higher disk/bandwidth cost.
- Direct prewarm:
direct_prewarm_latest_per_channel precaches the latest detected videos per channel during the YouTube scan.direct_prewarm_neighbors precaches the previous and next video in the same folder when a video is played.- Prewarm runs in background and is limited to avoid launching too many
yt-dlp resolutions at once.
Twitch
- If a live video is on air the !000-live-channel.strm will be created. The script will download the strm for each video in the /videos channel tab in any manner. Take a look at the limits and daterange values for videos in ./plugins/twitch/config.json.
- SponsorBlock doesn’t work in redirect mode, Twitch only works in direct mode at the moment.
- Season folders by year: Videos are organized in
Season {year} folders (e.g., Season 2025, Season 2026)
- Episode numbering: Files are named
S{year}E{XX} format, resetting to E01 each year
- Cookie authentication: Supports browser cookies for subscriber-only content
TV3
- Plugin for 3cat, content in Catalan.
Crunchyroll
Requieres a cookie file from Premium user login (you can extract the cookie file from Crunchyroll with browser extension like https://chrome.google.com/webstore/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc) or load a fresh cookie from browser (check discusion in https://github.com/yt-dlp/yt-dlp/issues/7442#issuecomment-1685036245).Requires yt-dlp nightly build to work. yt-dlp >=2024.05.22.232749.dev0Only works with login auth.I’m using a filter language your crunchyroll_audio_language config value and extractor crunchyrollbeta:hardsub=your crunchyroll_subtitle_language config value to get a version with one language and subs embeddedTo avoid constant rewriting of the strm files, a file called last_episode.txt is generated in the series directory, it contains the playlist position of the last strm downloaded, this will only generate strm for new episodes.- ~~Patch yt-dlp if Crunchyroll not works https://github.com/yt-dlp/yt-dlp/issues/7442#issuecomment-1637748442~~
mutate_values.json A particular file for this plugin. Overwrites the value of a specified field. For example, in cases where the season given by yt-dlp - season_number does not correspond to the actual season of the series. The available fields are as follows: season_number, season, episode_number, and episode.- ~~direct mode. On Crunchyroll, the direct mode inherits the functionality of the download mode. ~~
bridge mode. Given the latest updates, it is necessary to obtain the audio and video streams separately, redirect their output, and remux both tracks to finally serve them over HTTP. Experimental, sometimes it may fail to start playback and you need to try playing it again. There is no timestamp and it is not possible to navigate through the video’s timeline.With download mode, the audio and video streams will be downloaded separately, and after downloading, they will be remuxed to finally serve a final video/mp4 file. The files will be downloaded to ./temp/ and their lifespan will be 24 hours. This is configurable in config.json -> ytdlp2strm_temp_file_duration. The Crunchyroll plugin in download mode will automatically download the latest discovered episode of each series declared in channel_list.json.In the config.json file, and specifically for the Crunchyroll plugin, there are 4 parameters: jellyfin_preload_last_episode, jellyfin_base_url, jellyfin_user_id, and jellyfin_api_key. When configured with their correct values, they allow detecting if an episode is being played and pre-downloading the next one to achieve a seamless playback flow without interruptions.
A little script to serve yt-dlp video/audio as HTTP data throught Flask and dynamic URLs. We can use this dynamic URLs with youtube id video in url like http://127.0.0.1:5000/youtube/direct/FxCqhXVc9iY and open it with VLC or save it in .strm file (works in Jellyfin)
- Controller that loads plugins functions, used in crons to manage strm files
- Build strms manually:
cd /opt/ytdlp2STRM/ && python3 cli.py --media youtube --params direct
You can change --media value for another plugin
config/config.json
- ytdlp2strm_host
- ytdlp2strm_port
- ytdlp2strm_keep_old_strm
- ytdlp2strm_temp_file_duration
- ytdlp2strm_web_username (optional; enables HTTP Basic Auth on admin routes when both username and password are set)
- ytdlp2strm_web_password (optional; enables HTTP Basic Auth on admin routes when both username and password are set)
config/crons.json
-
Working with Schedule library (https://schedule.readthedocs.io/en/stable/examples.html)
-
Do attribute needs a list with commands [“–media”, “youtube”, “–params”, “direct”], replace youtube with your plugin name and direct with your prefered mode.
-
Custom timezone for each cron
-
direct : A simple redirect to final stream URL. (faster, no disk usage, sponsorblock not works)
-
bridge : Remuxing on fly. (fast, no disk usage)
-
download : First download full video then it’s served. (slow, temp disk usage)
-
iframe : The .strm stores the public YouTube watch URL (https://www.youtube.com/watch?v=<id>) instead of a ytdlp2STRM URL. Useful for players/apps that can play YouTube URLs natively without going through this service.
-
With download mode, the files in the temp folder older than 24h will be deleted.
- strm_output_folder
- channels_list_file
- days_dateafter
- videos_limit
- [YOUTUBE] sponsorblock
- [YOUTUBE] sponsorblock_cats
- [YOUTUBE] cookies *Required to obtain the manifest for age-protected videos. It can be (cookies-from-browser or cookies)
- [YOUTUBE] cookie_value *If you set cookies as browser cookies you must indicate the browser (i recommend firefox). In the case of cookies, you must indicate the cookie file path stored in text format
- [YOUTUBE] lang *Language for yt-dlp extractor
- [YOUTUBE] episode_format *Episode naming mode.
sequential uses incremental episode numbers; mmdd uses month/day style numbering.
- [YOUTUBE] video_quality *Maximum video height for yt-dlp playback selection. Use
best for no limit, or values like 1080, 720, 480.
- [YOUTUBE] download_subtitles *Download YouTube subtitles/auto-subtitles as
.vtt sidecar files and fix alignment/rollup issues for Jellyfin/Emby.
- [YOUTUBE] convert_subtitles_to_srt *Generate
.srt sidecar files from cleaned .vtt subtitles for better Android/TV compatibility.
- [YOUTUBE] keep_vtt_subtitles *Keep
.vtt files after SRT conversion. Set False to leave only .srt files.
- [YOUTUBE] direct_stream_cache_hours *TTL in hours for cached direct playback manifests stored in
<strm_output_folder>/.direct_cache.
- [YOUTUBE] direct_serve_media_playlist *Serve the selected HLS media playlist directly instead of the master playlist to improve Jellyfin/Emby startup time.
- [YOUTUBE] direct_prewarm_latest_per_channel *Number of latest videos per channel to prewarm during YouTube scans. Set
0 to disable.
- [YOUTUBE] direct_prewarm_neighbors *When a direct video is played, prewarm previous/next videos in background.
- [YOUTUBE] jellyfin_integration *Trigger a Jellyfin/Emby library scan after new YouTube STRM files are generated.
- [YOUTUBE] jellyfin_base_url *Base URL of your Jellyfin/Emby server.
- [YOUTUBE] jellyfin_api_key *API key used to trigger library scans.
- [YOUTUBE] jellyfin_library_name *Library name to refresh when new YouTube content is added.
[CRUNCHYROLL] crunchyroll_auth (browser, cookies or login), browser option in addition with background task opening firefox is the best way to keep unatended workflow.- ~~[CRUNCHYROLL] crunchyroll_browser (set if your choice in curnchyroll_auth is browser) You can read more about this searching --cookies-from-browser in https://github.com/yt-dlp/yt-dlp~~
[CRUNCHYROLL] crunchyroll_useragent (set if your choice in curnchyroll_auth is browser) Needs the same user agent that your browser. If you search current user-agent in Google you can see your user-agent, copy it.[CRUNCHYROLL] crunchyroll_username (set if your choice in curnchyroll_auth is login)[CRUNCHYROLL] crunchyroll_password (set if your choice in curnchyroll_auth is login)[CRUNCHYROLL] crunchyroll_cookies_file (set if your choice in curnchyroll_auth is cookies)[CRUNCHYROLL] crunchyroll_audio_language[CRUNCHYROLL] crunchyroll_subtitle_language <- embedded in video[CRUNCHYROLL] jellyfin_preload (False by default, set True to preload the next episode while the current is playing in Jellyfin)[CRUNCHYROLL] jellyfin_preload_last_episode (An @Floflo10 idea. False by default, set True to preloads the last episode at the time its strm is generated. Remember in 24h will be deleted from temp folder)[CRUNCHYROLL] jellyfin_base_url (Your Jellyfin URL, without final slash)[CRUNCHYROLL] jellyfin_user_id (Your Jellyfin user_id)[CRUNCHYROLL] jellyfin_api_key (Your Jellyfin api_key)
- [YOUTUBE] With “keyword-” prefix you can search for a keyword and this script will create the folders of channels founds dinamically and put inside them the strm files for each video. See an exaple in channel_list.example.json
- [YOUTUBE] Playlist needs “list-” prefix before playlist id, you can see an exaple in channel_list.example.json
- [YOUTUBE] If you want to get livestream from /streams youtube channel tab you need to add a new channel in channel_list with /streams (Check an example in ./plugins/youtube/channel_list.example.json)
- [TWITCH] This script makes a NFO file (tvshow.nfo) for each youtube or twitch channel (to get name, description and images). *Description only works in Linux systems at the moment
[CRUNCHYROLL] Only support URL series (not episodes), the script will create a folder for each serie, and subfolders for each season, inside season folder the strm episodes files will be created
Service
- LINUX: ytdlp2strm.service example service to run main.py with systemctl.
- WINDOWS: MS-TASK-ytdlp2STRM.xml example scheduled task with schtasks.
Jellyfin / Emby integration
ytdlp2STRM generates .strm files under the strm_output_folder configured in each plugin (plugins/<media>/config.json). Each .strm just contains a URL that points back to this service, so Jellyfin/Emby must have access both to the STRM files and to the ytdlp2STRM HTTP server (http://<host>:5000 by default).
Typical setup:
- Decide where the STRM files will live, e.g.
/media/Youtube on Linux or D:\media\Youtube on Windows.
- Make sure that same path is the
strm_output_folder value in plugins/youtube/config.json (and equivalent for Twitch/etc.).
- In Jellyfin/Emby create a Library of type “Shows” and point it to that folder (
/media/Youtube). Do the same for Twitch if you use that plugin.
- Each channel becomes a Show, each year a Season, and each video an Episode (
Channel [ID]/Season {year}/S{year}E{XX} - Video title.strm).
- In the ytdlp2STRM Youtube plugin config you can enable
jellyfin_integration so the service triggers a scan of the configured jellyfin_library_name after new STRM files are written. Populate jellyfin_base_url and jellyfin_api_key accordingly.
If Jellyfin runs on a different host/container than ytdlp2STRM, the URL stored inside the .strm files (http://127.0.0.1:5000/... by default) must be reachable from that host. Change ytdlp2strm_host in config/config.json to the IP/DNS name the Jellyfin server can reach.
Troubleshooting
FileNotFoundError: [WinError 2] The system cannot find the file specified (or the equivalent on Linux/macOS) when opening a direct URL or running the plugin from the Dashboard: the service tried to run yt-dlp as a subprocess but could not find the binary on PATH. Install yt-dlp as a binary (see the Prerequisite section) and restart the ytdlp2STRM service.- Cron runs but nothing happens / it always starts on the first channel: usually a symptom of the previous point. Check
ytdlp2strm.log for FileNotFoundError or command not found: yt-dlp.
- Dashboard › Run says
only python cli.py command can be executed from here: fixed in recent versions by resolving the interpreter server-side. If you still hit it, update to the latest version.
- Audio is in the wrong language even when
lang is set: YouTube videos with dubbed tracks default to the original. Recent versions add -S lang:<lang> automatically so the configured language is preferred. Update and restart.
Credits
评论