PulsorClip

🌟 Visual Showcase: Check out the PulsorClip Preview Gallery to see the UI.

Light Mode	Dark Mode

PulsorClip is a self-hosted media download and export workspace by Adriel Zimbril.

🚀 Project status

• 🌍 Web Workspace: ✅ 100% Functional
• 🤖 Telegram Bot: ✅ 100% Functional
• 🖥️ Desktop (Native): 🏗️ In Progress (Tauri)
• 📱 Mobile (Native): 🏗️ In Progress (Capacitor)

What It Is

PulsorClip gives you a controlled workflow for media downloads:

1. load a media URL first
2. choose mode, container, and quality
3. prepare the file on your own runtime
4. download only when the final file is actually ready

It is built for self-hosting, not for running a public downloader SaaS.

Why It Exists

• keep downloads explicit instead of automatic
• load media details before processing
• support browser and Telegram workflows from the same codebase
• stay portable enough to run on a single Docker service

Highlights

• ⚙️ Next.js 16 App Router web app
• 🤖 Telegram bot with guided download flow
• 🌍 Cookie-based i18n with en and fr
• 🌗 Light, dark, and system themes
• 📦 Video exports: mp4, webm, mkv
• 🎵 Audio exports: mp3, m4a
• 🧱 Shared yt-dlp plus ffmpeg core package
• 📈 Server-side progress tracking with manual final download
• 📚 Dedicated web pages for FAQ, Docs, and Deployment

Monorepo Structure

• apps/web
  • Next.js 16 App Router
  • cookie-based i18n
  • responsive Normal and Bulk workflows
  • FAQ, Docs, and Deployment pages
• apps/bot
  • Telegram bot with commands, inline keyboards, and admin notifications
  • maintenance mode support
  • guided mode, container, and quality selection
• packages/core
  • yt-dlp and ffmpeg orchestration
  • shared validation, progress, and i18n messages

Runtime Requirements

PulsorClip requires:

• Node.js 22+
• yt-dlp
• ffmpeg

For YouTube and some protected sources, authenticated cookies may also be required.

Local Development

npm install
npm run dev:web
npm run dev:bot

Useful commands:

npm run lint
npm run test
npm run build
npm start
npm run start:web
npm run start:bot

Notes:

• npm start launches the combined runtime via start:all
• for web-only local work, set TELEGRAM_BOT_ENABLED=false
• startup admin notifications only work if each admin account has already opened a private chat with the bot
• use PULSORCLIP_DEBUG_LOGS=true when diagnosing extractor failures on YouTube, Threads, Facebook, X, TikTok, or Instagram

Environment Files

• .env
  • your local runtime file
• .env.example
  • documented local template

Important variables:

• NEXT_PUBLIC_APP_URL
• PULSORCLIP_DEBUG_LOGS
• PULSORCLIP_LOG_FULL_URLS
• TELEGRAM_BOT_ENABLED
• TELEGRAM_BOT_TOKEN
• TELEGRAM_BOT_USERNAME
• TELEGRAM_ADMIN_IDS
• TELEGRAM_MAINTENANCE_MODE
• YTDLP_COOKIES_FROM_BROWSER
• YTDLP_COOKIES_FILE
• YTDLP_COOKIES_BASE64
• PULSORCLIP_DAILY_REPORT_ENABLED
• PULSORCLIP_DAILY_REPORT_HOUR
• PULSORCLIP_HEALTH_CHECK_CADENCE_MINS

Cookie Management

For YouTube and other protected platforms, PulsorClip supports multiple cookie management methods:

Option 1: Telegram Command (Recommended for VPS)

Admins can update cookies directly via Telegram using base64:

/cookies <base64-encoded-cookies>

Steps:

1. Export cookies from your browser using "Get cookies.txt" or "Cookie-Editor"
2. Generate base64: npm run encode-cookies ./cookies.txt ./cookies-base64.txt
3. Copy the base64 string from cookies-base64.txt
4. Send /cookies <base64-string> in Telegram

The cookies are stored in the metadata system and automatically used by both bot and web downloads.

Option 2: Encode Script

For local development or manual setup:

npm run encode-cookies ./cookies.txt ./cookies-base64.txt

This encodes your cookies.txt to base64. Set YTDLP_COOKIES_BASE64 to the base64 string value.

Option 3: Environment Variables

• YTDLP_COOKIES_FROM_BROWSER=chrome - Extract from local browser (dev only)
• YTDLP_COOKIES_FILE=/path/to/cookies.txt - Path to cookies file
• YTDLP_COOKIES_BASE64=<base64> - Base64 encoded cookies (best for VPS)

See docs/YOUTUBE-COOKIES.md for detailed instructions.

Deployment

- `PULSORCLIP_DEBUG_LOGS`: `true`.

Self-Hosting Dashboard

Platform	Deployment Method	One-Click	Status	Logo
Railway	railway.json	✅	Stable
Render	render.yaml	✅	Stable
Cloudron	CloudronManifest.json	✅	New
CapRover	captain-definition	✅	New
Coolify	docker-compose.yml	✅	Stable
Dokploy	docker-compose.yml	✅	Stable
Hostinger	docker-compose.yml	✅	Stable
HuggingFace	Docker Spaces	✅	Stable

---

Detailed Setup

• CapRover: Detection of captain-definition is automatic.
• Cloudron: Use cloudron install. Data is persisted in /app/data.
• Coolify/Dokploy: Standard Docker deployment on port 10000.

For detailed instructions, see docs/self-hosting.md.

Server

Current default target: Railway free Web Service with one Docker runtime for both web and bot.

Why this topology:

• avoids paid background workers
• keeps one deployable unit
• still supports Telegram polling and file preparation

Important limitation:

• free-tier storage is ephemeral, so prepared files can disappear after restart or redeploy

If you see this Telegram error:

409 Conflict: terminated by other getUpdates request

another polling instance is already running with the same bot token. Keep only one polling instance active, or disable the local bot with TELEGRAM_BOT_ENABLED=false.

Docs

Web pages included in the app:

• /faq
• /docs
• /deployment

Repository docs:

• README.fr.md
• docs/DEPLOYMENT.md
• docs/TELEGRAM-BOT.md
• docs/YOUTUBE-COOKIES.md
• docs/SELF-HOSTING.md

Telegram Bot Commands

Public Commands

• /start - Start the guided download flow
• /language - Choose your preferred language
• /help - Show commands and usage examples
• /video <url> - Download video from a URL
• /audio <url> - Download audio from a URL
• /track <job_id> - Track a specific job status
• /support - Get help or contact the operator
• /status - View Bot services availability
• /queue - View your active jobs and queue

Admin Commands

• /status - View Bot & Web live counters
• /server - Detailed server diagnostics
• /health - Send health snapshot to admins
• /report - Current daily statistics
• /daily - Trigger daily report
• /broadcast - Message all bot users
• /users - User base statistics
• /cookies - Manage yt-dlp cookies (update via Telegram)

Community files:

• CODE_OF_CONDUCT.md
• CONTRIBUTING.md
• SECURITY.md

CI

GitHub Actions validation is included:

• lint
• unit tests
• build

See .github/workflows/ci.yml.

Platforms

Platform	Status	Extraction Method
Threads	✅ Stable	Custom JSON Scraper (up to 1280p)
TikTok	✅ Stable	Tikwm API + Carousel Fallback
Instagram	✅ Stable	yt-dlp + direct CDN fallback
Facebook	✅ Stable	yt-dlp
X / Twitter	✅ Stable	yt-dlp
YouTube	⚠️ Restricted	Stable locally. "Sign in to confirm" errors common on VPS/Datacenter IPs. Use authenticated cookies to bypass.

Legal & Educational Disclaimer

PulsorClip is an educational and research project.

It is designed to explore media extraction concepts and self-hosting architectures. The author(s) do not encourage or condone the unauthorized downloading, distribution, or storage of copyrighted material.

• User Responsibility: Users are solely responsible for their actions and must ensure compliance with the terms of service of the target platforms and local copyright laws (DMCA, etc.).
• Notice: This software is provided "as is", without warranty of any kind. The authors are not responsible for any legal consequences or liability arising from the use or misuse of this software.