🎵 Hanasuba Music Service v2.0

YouTube to MP3 download service with Camoufox stealth cookies

Built for Hanasuba backend.

---

✨ Features

• ✅ Stealth cookies - Camoufox anti-detection Firefox
• ✅ Auto-refresh - Cookies refresh every 14 days automatically
• ✅ Bot detection bypass - Works around YouTube rate limiting
• ✅ Audio-only downloads - MP3 192kbps (configurable)
• ✅ Streaming support - HTTP range requests for audio players
• ✅ Metadata extraction - Title, artist, duration, thumbnail
• ✅ Retry logic - Auto-retry with fresh cookies if blocked
• ✅ REST API - Simple JSON API for integration

---

🏗️ Architecture

music-service (Node.js + Python)
├── Express API (Node.js)
│   ├── Download orchestration
│   └── File streaming
├── Camoufox (Python)
│   ├── Stealth cookie extraction
│   └── Cookie validation
└── yt-dlp
    └── YouTube download (using stealth cookies)

Why this stack?

• Camoufox = Undetectable Firefox (bypasses bot detection)
• yt-dlp = Best YouTube downloader (handles all edge cases)
• Node.js = Fast I/O for streaming

---

📦 Installation

Prerequisites

• Node.js 18+
• Python 3.9+
• yt-dlp
• ffmpeg

Install

# Clone repo
git clone https://git.etheryale.com/StillHammer/videotomp3transcriptor.git
cd videotomp3transcriptor
git checkout music-service-v2

# Install Node dependencies
npm install

# Install Python dependencies + browsers
npm run setup

# Configure
cp .env.example .env
nano .env  # Edit PORT, STORAGE_PATH, etc.

# Start
npm start

---

🚀 Usage

Start server

npm start

Server runs on http://localhost:8889 (configurable via .env)

API Endpoints

POST /download

Download YouTube video to MP3.

curl -X POST http://localhost:8889/download \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ"}'

Response:

{
  "success": true,
  "title": "Rick Astley - Never Gonna Give You Up",
  "duration": 212,
  "artist": "Rick Astley",
  "filePath": "/var/hanasuba/music/dQw4w9WgXcQ.mp3",
  "fileName": "dQw4w9WgXcQ.mp3",
  "youtubeId": "dQw4w9WgXcQ",
  "thumbnail": "https://..."
}

GET /stream/:filename

Stream MP3 file (supports range requests for seeking).

curl http://localhost:8889/stream/dQw4w9WgXcQ.mp3 --output song.mp3

DELETE /file/:filename

Delete downloaded file.

curl -X DELETE http://localhost:8889/file/dQw4w9WgXcQ.mp3

GET /health

Health check.

curl http://localhost:8889/health

POST /admin/refresh-cookies

Force refresh cookies (normally automatic).

curl -X POST http://localhost:8889/admin/refresh-cookies

---

🍪 How Cookies Work

Automatic Refresh

Cookies are automatically refreshed in these cases:

1. Every 14 days (proactive refresh)
2. On startup (if invalid)
3. Every 12 hours (validation check)
4. On bot detection (retry with fresh cookies)

Manual Refresh

# Via API
curl -X POST http://localhost:8889/admin/refresh-cookies

# Via npm script
npm run cookies:extract

Validation

# Check if cookies are valid
npm run cookies:validate

---

🔧 Configuration

Environment Variables

See .env.example:

PORT=8889                           # Server port
STORAGE_PATH=/var/hanasuba/music   # Where to save MP3 files
PYTHON_PATH=python3                 # Python binary
YTDLP_PATH=yt-dlp                   # yt-dlp binary
ALLOWED_ORIGINS=*                   # CORS

Audio Quality

Pass quality parameter in download request:

{
  "url": "https://youtube.com/watch?v=...",
  "quality": "320k"  // or "192k" (default), "128k"
}

---

🐛 Troubleshooting

"Sign in to confirm you're not a bot"

Solution: Cookies have expired or are invalid.

# Force refresh
curl -X POST http://localhost:8889/admin/refresh-cookies

# Or restart service (auto-refresh on startup)
npm start

yt-dlp not found

# Install yt-dlp
pip install yt-dlp
# or
sudo apt install yt-dlp

Camoufox install fails

# Manual install
pip install camoufox camoufox-captcha playwright
playwright install firefox

Downloads slow

This is normal. YouTube throttles downloads. The service uses mweb client for best speed.

---

🔐 Security

• Cookies file permissions: 600 (owner read/write only)
• Cookies never logged or exposed
• Cookies stored locally only
• CORS configurable via ALLOWED_ORIGINS

---

🚢 Deployment

PM2 (recommended)

pm2 start src/server.js --name music-service
pm2 save
pm2 startup

systemd

[Unit]
Description=Hanasuba Music Service
After=network.target

[Service]
Type=simple
User=debian
WorkingDirectory=/home/debian/videotomp3transcriptor
ExecStart=/usr/bin/node src/server.js
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl enable music-service
sudo systemctl start music-service

---

📊 Monitoring

Check service status:

# Health check
curl http://localhost:8889/health

# Cookies status
curl http://localhost:8889/admin/cookies-status

# Logs (PM2)
pm2 logs music-service

# Logs (systemd)
journalctl -u music-service -f

---

🔗 Integration with Hanasuba

Hanasuba (Rust) calls this service via HTTP:

// In Hanasuba src/music/client.rs
let response = reqwest::Client::new()
    .post("http://localhost:8889/download")
    .json(&json!({ "url": youtube_url }))
    .send()
    .await?;

let result: DownloadResult = response.json().await?;
// Save metadata to PostgreSQL

---

📝 Development

# Dev mode (auto-restart on changes)
npm run dev

# Extract cookies manually
npm run cookies:extract

# Validate cookies
npm run cookies:validate

---

🆚 v1 vs v2

Feature	v1 (legacy)	v2 (current)
Cookies	Firefox standard	Camoufox stealth
Auto-refresh	❌ Manual	✅ Automatic (14 days)
Bot detection	❌ Fails often	✅ Auto-retry
Validation	❌ None	✅ Every 12h
Reliability	~60%	~95%
Transcription	✅ OpenAI Whisper	❌ Removed (not needed)
Translation	✅ Claude	❌ Removed (not needed)

v2 is focused on one thing: reliable YouTube → MP3 downloads.

---

📄 License

MIT

---

🙏 Credits

• Camoufox - Stealth Firefox
• yt-dlp - YouTube downloader
• Hanasuba - Main backend

---

Built with ❤️ for Hanasuba