Skip to content

Discord Mobile Ingestion & Pipeline Architecture

Architecture blueprint for the zero-friction, mobile-first media intake pipeline. Combines MeTube-style interactive options with Discord UI components, channel auto-routing, and automated metadata tagging for self-hosted libraries.

1. End-to-End Ingestion Flow

The following sequence diagram details how a link shared from a mobile device flows through Discord, triggers the background Python engine, and lands in your media libraries:

sequenceDiagram
    autonumber
    actor User as You (Mobile / Desktop Discord)
    participant Bot as Homelab Discord Bot
    participant Engine as Ingestion Engine (yt-dlp + mutagen)
    participant Storage as /srv/storage (Libraries)

    User->>Bot: Pastes link (YouTube, Bandcamp, Soundcloud, etc.)
    Bot->>Engine: Fast probe metadata (Title, Uploader, Thumbnail)
    Bot-->>User: Replies with Rich Embed + Dropdowns + [Download] Button
    User->>Bot: Selects "🎵 MP3 (320k)" & "🎶 Music", taps [Download]
    Bot-->>User: Updates message to ⏳ "Downloading & tagging..."
    Bot->>Engine: Run download + mutagen metadata embedding
    Engine->>Storage: Move to /srv/storage/media/music/Artist/Album/
    Bot-->>User: Updates message to ✅ "Complete! Added to Navidrome."

2. Discord Interactive Widget Specification (Pattern A)

When a link is posted or requested via /intake, the bot renders an interactive Discord message with embedded preview and dropdown menus:

Component Breakdown

  1. Rich Embed Header:
  2. Title: Track / Video Name
  3. Author: Channel / Artist Name
  4. Thumbnail: Video artwork fetched dynamically via yt-dlp --dump-json

  5. Duration / Source: Video length and original URL domain

  6. Dropdown Menu 1: Format & Quality (discord.ui.Select):

  7. 🎵 Audio: Lossless FLAC → Extracts audio, transcodes to FLAC
  8. 🎵 Audio: High Quality MP3 (320kbps) → Standard high-bitrate MP3
  9. 🎵 Audio: Opus / M4A → Native web audio container (compact & high fidelity)
  10. 🎬 Video: 1080p (MP4) → Full HD video with AAC audio

  11. 🎬 Video: Best Available → Highest resolution available (4K/1440p/1080p)

  12. Dropdown Menu 2: Target Destination (discord.ui.Select):

  13. 🎶 Music Library → /srv/storage/media/music (served by Navidrome)
  14. 🎧 Audiobooks & Podcasts → /srv/storage/media/audiobooks (served by Audiobookshelf)

  15. 🎬 Video Archive → /srv/storage/media/video (served by Jellyfin)

  16. Action Buttons (discord.ui.Button):

  17. [ 🚀 Start Ingestion ] (Green / Success): Initiates background job
  18. [ ✕ Cancel ] (Secondary / Red): Dismisses widget and clears cache

3. Dedicated Channel Strategy

To maximize zero-idle efficiency and minimize typing on mobile:

Channel Default Ingestion Profile Destination Library
#music-intake Best Audio → MP3 320k or FLAC + ID3 Tagging /srv/storage/media/music (Navidrome)
#video-intake 1080p MP4 + Video Metadata /srv/storage/media/video (Jellyfin)
#audiobook-intake M4B / MP3 + Chapter & Cover Extraction /srv/storage/media/audiobooks (Audiobookshelf)
#homelab-commands Interactive MeTube Widget (Pattern A) + Telemetry (/status, /ml on) User-selected

4. Pipeline Engine Architecture

The Python engine operates independently of Discord so it can be triggered from CLI, Cron, or Webhooks:

pipeline/
├── cli.py             # Standalone CLI interface (e.g., python -m pipeline --url ... )
├── downloader.py      # yt-dlp wrapper with format selectors & progress hooks
├── tagger.py          # mutagen ID3 / Vorbis / MP4 tagger + cover art embedding
└── router.py          # Organizes files by Artist/Album and handles filesystem moves

[!TIP] Zero-Idle Guarantee: The Discord bot runs as an asynchronous, single-threaded Python container consuming only ~30–40 MB of RAM while idling. Ingestion workers spawn only when a job is accepted and release memory immediately upon completion.