Media Pocket

Media Pocket turns Telegram into a personal entry point for media. A user sends a link, several links, or a file; the bot identifies the source, queues the work, shows progress, and returns the finished video, audio, document, or album. Each instance runs on its operator’s server, and only administrators and invited users can use it.

Links, files, and collections

The bot handles YouTube video, social posts from TikTok, Instagram, X, Threads, and Pinterest, audio sources, and direct HTTP(S) media links. Other addresses can be resolved through yt-dlp when it supports the source. Compatibility with any particular service depends on its current restrictions and the credentials available to the deployment.

An ordinary link starts a download without a separate selection card. Audio-first sources stay audio; for YouTube, each user saves a preference for video, audio, or “always ask.” When a URL contains a playlist, the bot first asks whether to download the current video or the whole collection. Videos with usable description timestamps can be split into tracks: audio is downloaded once, cut at the detected boundaries, and delivered in groups with titles and metadata.

Batches, albums, playlists, and files uploaded directly to Telegram use the same job pipeline. Results arrive separately from technical status and optional actions. A failed download leaves a compact card with a readable explanation and a retry action, rather than a traceback from the external provider.

State and background processes

The interactive bot and worker are separate processes within one modular application. PostgreSQL holds canonical state; an active job and its transactional outbox record are created atomically. A publisher moves job identifiers into Redis Streams, workers receive work through a consumer group, and a separate event stream reports progress. Shared artifact storage connects file retrieval to delivery in Telegram.

A worker does not construct a Telegram client: it identifies the provider, retrieves and processes media, and writes the result. The bot owns messages, callback actions, and delivery. This boundary lets background processes scale independently without holding one Telegram handler open for the entire download.

Persisted state does not imply indefinite automatic continuation. The README explicitly notes that starting the bot cancels active background jobs and clears the queue. An uncertain delivery outcome must not silently trigger another send either: the architecture provides an explicit manual retry action. File size, concurrency, processing deadlines, and completed-artifact retention are bounded by configuration.

Preparing media for Telegram

Media Pocket prefers a compatible source format over mandatory transcoding. For native playback, that means H.264/AAC video and compatible M4A/AAC or MP3 audio. Suitable streams are remuxed without re-encoding; FFmpeg converts the incompatible stream or the complete file only when necessary. File delivery preserves the downloaded original where possible.

For a heavy direct media URL, the bot can offer the original or a compact version after examining duration, bitrate, and resolution. In compact mode, FFmpeg reads the HTTP stream while encoding, so a complete original does not first have to be stored as an intermediate file. User-uploaded audio and video are normalized by the same pipeline; ordinary documents remain files.

Access and credentials

An administrator is created from the command line before the first startup. Administrators issue single-use invitations or codes with a redemption limit or expiry. Access checks cover private and group messages, inline mode, and callback actions; another user must not confirm, cancel, or retry someone else’s work.

Sources that require browser authentication use cookies. An optional integration with Media Cookie Broker refreshes separate cookie files; the broker is deployed independently, and its endpoint, credentials, and network access are operator choices. Direct Spotify audio requires a valid Premium session and a separate helper based on librespot; a failure on that path does not substitute a search result for the requested recording.

Bot tokens, cookies, Spotify sessions, and database dumps remain deployment secrets. PostgreSQL, Redis, the local Telegram Bot API, and auxiliary services should not be exposed to the public internet. Invite-only access does not make leaked server credentials safe.

Deployment and project limits

The standard setup uses Linux, Docker Compose, Python 3.14, PostgreSQL, Redis, a local Telegram Bot API, and FFmpeg. Migrations run as a separate role; worker count is configured independently of the bot. Updates require reviewing the chosen revision, backing up the canonical database, and checking migration compatibility: reverting source code alone does not revert the schema or data.

These are early, self-hosted 0.1.x releases. Media Pocket does not bypass provider access controls: deleted, private, or region-restricted material may remain unavailable even with valid cookies. Supported sources and external-service requirements can change; the open-source README contains the current installation instructions, configuration, and limitations.