No description
  • Go 99.3%
  • Dockerfile 0.7%
Find a file
kimi-code 47854840be
All checks were successful
ci / image (push) Successful in 29s
ci: skip pull in mirror-image when the image is already in dind
dock.mau.dev stalls dind's pulls (IPv6 blackhole); the image can be
pre-loaded with kubectl cp + docker load instead.
2026-11-14 01:56:40 +03:00
.forgejo/workflows ci: skip pull in mirror-image when the image is already in dind 2026-11-14 01:56:40 +03:00
cmd/matrix-jellyfin-album-adder Port from Telegram to Matrix (chat.blya.by) 2026-11-13 06:46:46 +03:00
deploy Port from Telegram to Matrix (chat.blya.by) 2026-11-13 06:46:46 +03:00
internal Port from Telegram to Matrix (chat.blya.by) 2026-11-13 06:46:46 +03:00
.dockerignore initial commit 2026-09-23 14:09:35 +03:00
.gitignore initial commit 2026-09-23 14:09:35 +03:00
Dockerfile Port from Telegram to Matrix (chat.blya.by) 2026-11-13 06:46:46 +03:00
go.mod Port from Telegram to Matrix (chat.blya.by) 2026-11-13 06:46:46 +03:00
go.sum Port from Telegram to Matrix (chat.blya.by) 2026-11-13 06:46:46 +03:00
README.md Port from Telegram to Matrix (chat.blya.by) 2026-11-13 06:46:46 +03:00

matrix-jellyfin-album-adder

Matrix bot that turns a YouTube playlist into an album in a Jellyfin music library.

Send it a playlist link. It reads the playlist and every video's metadata, then asks who the artist is — the channel, whoever the descriptions credit, and anything already in the library that looks like a match. Tap a name and it does the long part on its own: downloads every video as FLAC, tags the tracks, writes them into the library and hands them to Jellyfin to scan. All of that shows in one message it keeps editing.

Every question comes before the download, so you answer while the bot is quick to reply and can leave once it starts. Reading the metadata asks YouTube about each video, a few seconds apiece; it's still far quicker than fetching the audio.

Send it a single video — a watch?v=…, a youtu.be/…, a short — and it does the same with that one song, filed as a one-track single. The album defaults to the song's own title, or the album its metadata names; the same artist choices appear, and typing Artist / Album still sets both. A link that carries both a video and a playlist is still taken as the playlist.

A video over half an hour long is a sizeable FLAC — a full concert or DJ set can run past a gigabyte — so for those the first question is whether to keep the lossless FLAC or convert to a much smaller MP3, and the artist comes next:

🎧 Boiler Room: Four Tet
Four Tet

⏱ That's 1 h 28 m. As FLAC it'll be a hefty file.

🎼 Keep it lossless, or save space with MP3?
💎 Keep FLAC
🎵 Convert to MP3
🛑 Cancel

Each of those lines carries a reaction — tap the one that answers. Matrix has no inline buttons, so reactions are how this bot asks: the options are listed in the message and hang off it as emoji, and the bot's own reactions are taken back down once a question is answered.

A playlist, from link to library:

🎧 Les Voyages de l'âme
Alcest - Topic · 8 tracks

⏳ Reading the tracks — 5 of 8
🎧 Les Voyages de l'âme
Alcest - Topic · 8 tracks
💿 Les Voyages de l'âme (2012)
🎵 8 tracks · 52 minutes, as FLAC

👤 Who is the artist?
1️⃣ 📁 Alcest
2️⃣ 📺 Alcest - Topic
3️⃣ 📝 Neige
✍️ Type it myself
🛑 Cancel
🎧 Les Voyages de l'âme
Alcest - Topic · 8 tracks
💿 Alcest — Les Voyages de l'âme (2012)

⬇️ Downloading track 5 of 8 — 63%
██████████░░░░░░
Icon Where the suggestion came from
📁 an artist already in the library, spelled the way the library spells it
📺 the channel the playlist belongs to
🎼 the music metadata YouTube attaches to auto-generated videos
📝 credits in the video descriptions
🔤 the Artist - Track half of the video titles

Nothing found that fits? Type it myself (✍️) takes the name from your next message. Typing Artist / Album (spaces around the slash) sets the album name too.

To talk to the bot, invite it to a room (or open a direct chat) — it accepts every invite. !help shows the rundown, !cancel stops whatever it's working on in that room.

About the audio

YouTube only ever serves lossy audio — Opus or AAC. The bot takes the best stream there is and decodes it once into FLAC: no second lossy generation, and one format across the library. It is as close to the source as the source allows, not a way to make a lossy file lossless.

Playlists are always FLAC. A single video over half an hour offers MP3 as well, for when the lossless file would be larger than the content is worth; the MP3 is -q:a 0 VBR (around 245 kbps), tagged the same way with ID3 frames instead of Vorbis comments.

Where files land

The layout is the one Lidarr writes and Jellyfin reads:

$MUSIC_ROOT/Alcest/Alcest/Les Voyages de l'âme/
├── 01 - Autre Temps.flac
├── 02 - Là où naissent les couleurs nouvelles.flac
└── folder.jpg
  • Tracks are retagged (ARTIST, ALBUMARTIST, ALBUM, TITLE, TRACKNUMBER, DATE, and the video URL in COMMENT) by stream copy, so the audio and the embedded cover are untouched.
  • An album is built in WORK_DIR and moved into place in one step, so a scan never catches it half-written.
  • If the artist already exists, the library's own spelling of the folder is reused rather than a near-duplicate created next to it.
  • If the album folder already exists, its files are left alone: anything with a name that isn't taken is added, and the rest is reported back.
  • Jellyfin is told about the one new folder (POST /Library/Media/Updated) rather than asked for a full refresh.

Requirements

  • Go 1.26+
  • ffmpeg and ffprobe in PATH
  • yt-dlp in PATH
  • A Matrix account for the bot on the homeserver — the bot logs in as a plain user; rooms it talks in are not end-to-end encrypted
  • Write access to the music library, as a user Jellyfin can read back (uid 1001 on trumbeak)

Configuration

Variable Required Description
MATRIX_USERNAME + MATRIX_PASSWORD one of the two The bot account's login. MATRIX_USERNAME is a localpart (album-adder) or a full user ID
MATRIX_USER_ID + MATRIX_ACCESS_TOKEN one of the two Or skip the password login and use an existing session's token
MATRIX_HOMESERVER no Base URL of the homeserver. Default https://chat.blya.by
MUSIC_ROOT yes The library folder holding the artist folders, e.g. /media/Music
ALLOWED_USERS no Comma-separated Matrix user IDs, e.g. @aken:chat.blya.by. Unset means anyone can write to your library
WORK_DIR no Where playlists are downloaded. Default $MUSIC_ROOT/.album-adder, which keeps the final move on one filesystem
JELLYFIN_URL no e.g. http://jellyfin:8096. Without it, suggestions come from the folders on disk and the server picks albums up on its next scan
JELLYFIN_TOKEN with JELLYFIN_URL An API key from Jellyfin's Dashboard → API Keys
JELLYFIN_MUSIC_ROOT no MUSIC_ROOT as the Jellyfin server sees it, when the two mount the library at different paths
MAX_TRACKS no Longest playlist accepted, default 200
PROXY_URL no socks5://user:pass@host:1080, http://host:3128 or https://…. If unset, HTTPS_PROXY/ALL_PROXY are used
YOUTUBE_COOKIES no Path to a Netscape cookies.txt from a browser signed in to YouTube. Needed once YouTube answers "Sign in to confirm you're not a bot" for the proxy's address. Each yt-dlp run gets a private copy, so the file can be read-only. Missing at startup means running without

PROXY_URL is passed to yt-dlp as well, so YouTube downloads take the same route as the bot. Jellyfin is reached directly, since it's on the local network.

With socks5://, DNS is resolved by the proxy, so blocked DNS for the homeserver is not a problem.

Run

export MATRIX_USERNAME=album-adder
export MATRIX_PASSWORD=…
export MATRIX_HOMESERVER=https://chat.blya.by
export MUSIC_ROOT=/mnt/media/downloads/Music
export ALLOWED_USERS=@aken:chat.blya.by
export JELLYFIN_URL=http://192.168.2.3:8096
export JELLYFIN_TOKEN=...
go run ./cmd/matrix-jellyfin-album-adder

Deploy

deploy/matrix-jellyfin-album-adder.yaml is the Deployment for trumbeak's cluster: the same /var/mnt/media/downloads hostPath Jellyfin uses, mounted at the same /media, running as uid 1001. A gost sidecar is the bot's PROXY_URL: trumbeak can't reach YouTube directly, so downloads depend on it as much as Matrix does. It reads the cluster's shared gost secret. The bot's Matrix account has to be registered on chat.blya.by first; create the bot's own secret next — the comment at the top of the file has the command. The applied copy, with a sealed secret, is server/apps/matrix-jellyfin-album-adder in the nix repo.

Tagging v1.2.3 makes CI publish git.blya.by/assisken/tg-jellyfin-bot:1.2.3 — the image keeps the repository's name.

Limits

  • One playlist per room, one download at a time across the bot.
  • Jobs live in memory: a restart loses whatever was in flight, and its half-finished download is cleaned up on the next sweep rather than resumed.
  • Videos that are private, deleted or blocked are skipped; the rest of the playlist still lands.