Media Tools

Media Tools is a React and Node.js application for media conversion, public media downloading, Telegram delivery, analytics, and Railway-based production operations.

Live site: media-tools.app

Useful public entry points:

• Resources - workflow guides for downloads, compression, file cleanup, and Telegram delivery.
• Video Downloader - public media links from supported platforms.
• YouTube Video Downloader - high-intent YouTube download page.
• Instagram Reels Downloader - public Reels and Instagram media.
• TikTok Downloader No Watermark - public TikTok video links.
• Compress MP4 Online - video compression entry point.
• Trim Video Online - clean video trimming page for uploaded files.
• Remove Audio from Video - mute video workflow.
• Compress Image Online - image compression entry point.
• Remove Image Metadata - clean image export workflow.
• Media File Size Cheat Sheet - linkable compression guide.
• Telegram Bot - mobile-first media link workflow.

Tech Stack

Frontend — React 18, React Router, Vite, Web Vitals, GA4 Backend — Node.js 20+, Express, Helmet, ES modules Telegram — Grammy + local Telegram Bot API server (2 GB native uploads) Media — FFmpeg / ffprobe (fluent-ffmpeg), yt-dlp, sharp (images) Storage — Cloudflare R2 via AWS SDK, better-sqlite3, PostgreSQL, Redis Infra — Railway (two services), Docker, Playwright (E2E)

Features

• Image Converter - converts browser-compatible image formats such as JPG, PNG, WEBP, and AVIF.
• Video Converter - converts common video formats such as MP4, GIF, WEBM, and MOV.
• Video Downloader - downloads supported public media from YouTube, Instagram, TikTok, X/Twitter, Rutube, and direct media URLs where supported by the backend.
• Music Downloader - downloads supported public audio from YouTube and SoundCloud.
• Telegram Bot - uses the same media pipeline as the web app and can deliver larger files through the local Telegram Bot API server.
• Large Download Worker - handles long-running YouTube full-video downloads through persistent jobs and R2 delivery.
• Unavailable Media Detection - stops deterministic private, deleted, removed, or not-found media early while avoiding false positives for bot checks, timeouts, proxy failures, and auth gates.
• Redis TTL State - optional Railway Redis-backed short-lived state for inline cache, rate buckets, duplicate locks, and unavailable-media cache entries.

Quick Start

Prerequisites

• Node.js 20+ recommended.
• FFmpeg and ffprobe available in PATH, or explicit FFMPEG_PATH / FFPROBE_PATH.
• yt-dlp available through the configured server runtime.

Install

npm install
cd client && npm install
cd ../server && npm install

Development

npm run start

This starts the backend and Vite frontend together. The frontend dev server is configured at http://localhost:3000.

Production Build

npm run build
cd server && npm start

Telegram Bot

The bot is optional for local development. In production it runs as the telegram-bot Railway service with the local Telegram Bot API server in the same container.

Local bot startup:

cd server
TELEGRAM_BOT_TOKEN=your_token_here node botEntry.js

Production bot delivery uses:

• Standard Telegram Bot API for regular bot interactions and medium files.
• Local Bot API with file:// paths for larger Telegram-native uploads.
• R2 signed links for files that exceed Telegram-native delivery limits.
• Inline mode returns direct/proxied media results and does not upload cache media into the admin's private chat by default.

See docs/TELEGRAM_BOT.md, docs/large-file-uploads.md, and docs/telegram-youtube-operational-notes.md.

Deployment

Railway deploys from GitHub. Do not use railway up for normal production deploys because GitHub push triggers deployment automatically.

Service	Config file	Runtime
media-tools-web	railway.web.json	HTTP API, frontend, background worker, bgutil-pot
telegram-bot	railway.bot.json	Grammy bot, local Telegram Bot API server, bgutil-pot
Redis	Railway database service	Optional TTL state for cache, locks, and rate buckets

Required production references:

• docs/RAILWAY.md
• docs/railway-variables.md
• docs/DDOS_PROTECTION.md

Environment Variables

Use .env.example for local development and docs/railway-variables.md for Railway.

Common production variables:

• SESSION_SECRET - session encryption key.
• API_URL - canonical public base URL used by the bot and callbacks.
• ADMIN_SECRET - admin-only API access.
• ALLOWED_ORIGINS - comma-separated CORS origins.
• RAILWAY_PROXIES_CONTENT - proxy list for supported platform access.
• RAILWAY_COOKIES_BASE64 or RAILWAY_COOKIES_CONTENT - cookie transport for platform access.
• TELEGRAM_BOT_TOKEN - Telegram bot token.
• TELEGRAM_API_ID and TELEGRAM_API_HASH - required by local Telegram Bot API server.
• REDIS_URL - optional Railway Redis reference, usually ${{Redis.REDIS_URL}}.
• TELEGRAM_INLINE_NATIVE_CACHE_ENABLED - keep false unless a dedicated cache chat is configured.
• TELEGRAM_INLINE_CACHE_CHAT_ID - dedicated cache chat used only when native inline file_id caching is enabled.

Proxy and health-check safety:

• Keep PROXY_HEALTH_CHECK_ENABLED=false in production unless running a short manual diagnostic.
• Keep PROXY_HEALTH_CHECK_FULL_SWEEP=false; full proxy sweeps can burn paid proxy traffic.
• Keep POT_TOKEN_HEALTH_CHECK_ENABLED=false; real YouTube downloads request poTokens on demand.

Project Structure

media-tools/
+-- client/              # React + Vite frontend
+-- server/              # Node.js + Express backend
|   +-- core/            # Domain model, errors, metrics, platform parsing
|   +-- routes/          # HTTP API routes
|   +-- services/        # Downloaders, conversions, bot, uploads, workers
+-- scripts/             # Railway helpers, exports, operational checks
+-- docs/                # Operating and architecture documentation
+-- railway.*.json       # Railway service configs

Commands

Root:

npm run start
npm run build
npm run check-links
npm run test:youtube-shorts
npm run railway-check

Server:

cd server
npm run typecheck
npm test

Client:

cd client
npm run dev
npm run build

Documentation

Start with docs/README.md. It groups the documentation into canonical and operational references.

Important current docs:

• docs/architecture.md
• docs/api.md
• docs/RAILWAY.md
• docs/railway-variables.md
• docs/TELEGRAM_BOT.md
• docs/REDIS.md
• docs/architecture/youtube-download.md
• docs/DDOS_PROTECTION.md

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, conventions, and the checks that must pass before a pull request. Report security issues privately per SECURITY.md.

Terms of Use

Use this software only for lawful access to public or owned media. Do not use it to violate copyright, bypass paywalls, access private content without permission, harass others, or violate third-party platform terms.

THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. THE AUTHORS SHALL NOT BE LIABLE FOR DAMAGES ARISING FROM USE OF THIS SOFTWARE.