nqdev/py-restream repository overview

⁠🇻🇳 Hướng dẫn sử dụng chi tiết — py-restream

Chào mừng bạn đến với py-restream, giải pháp Python chuyên nghiệp để restream TikTok Live lên YouTube Live 24/7.

⁠🚀 Tính năng nổi bật (v1.1.0)

• 🖥️ Web Dashboard Mới: Điều khiển toàn bộ qua trình duyệt (Start/Stop/Logs).
• 🐳 Docker Ready (v1.1.0): Hình ảnh siêu nhẹ, triển khai 1-click trên Linux/VPS.
• ⚡ Tối ưu CPU: Chế độ Stream Copy giúp giữ nguyên chất lượng video mà không tốn CPU.
• 🔄 Tự động 100%: Tự động lấy link TikTok, tự động kết nối lại khi rớt mạng.
• 🔌 3 Chế độ Input: Username, Direct TikTok URL, hoặc RTMP Bypass.

⁠📦 1. Cài đặt nhanh

1. Chuẩn bị Python & FFmpeg:
   • Cài đặt Python 3.11+.
   • Cài đặt FFmpeg và thêm vào PATH hệ thống.
2. Cài đặt thư viện:

   python -m venv venv
   .\venv\Scripts\activate  # Windows
   source venv/bin/activate  # Linux
   pip install -r requirements.txt
   

   Copy
3. Cấu hình: Tạo file .env và điền YOUTUBE_STREAM_KEY.

⁠🐳 2. Sử dụng Docker (Khuyên dùng cho Server/VPS)

Đây là cách tốt nhất để chạy 24/7 mà không lo ngại về môi trường. Bạn có thể sử dụng hình ảnh dựng sẵn (pre-built) từ Docker Hub.

⁠Cách 1: Sử dụng Docker Hub (Nhanh nhất)

1. Tạo file docker-compose.yml:

   version: '3.8'
   services:
     py-restream:
       image: nqdev/py-restream:latest
       container_name: py-restream-app
       restart: unless-stopped
       ports:
         - "8000:8000"
       environment:
         - TZ=Asia/Ho_Chi_Minh
         - YOUTUBE_STREAM_KEY=your-stream-key
         - TIKTOK_USERNAME=@your-tiktok-user
       volumes:
         - ./logs:/app/logs
   

   Copy
2. Khởi chạy: docker-compose up -d

⁠Cách 2: Chạy trực tiếp từ CLI

docker run -d \
  --name py-restream-app \
  -p 8000:8000 \
  -e YOUTUBE_STREAM_KEY="your-stream-key" \
  -e TIKTOK_USERNAME="@your-tiktok-user" \
  -v ${PWD}/logs:/app/logs \
  nqdev/py-restream:latest

• Theo dõi Log: docker logs -f py-restream-app
• Ưu điểm: Tối ưu CPU, tích hợp sẵn FFmpeg, không cần cấu hình trên host.

⁠🖥️ 2. Sử dụng Web Dashboard (Khuyên dùng)

Đây là cách dễ dàng nhất để quản lý luồng stream.

• Khởi chạy (Windows): Chạy file run_webapp.bat.
• Khởi chạy (Linux): Chạy file ./run_webapp.sh.
• Truy cập: Mở trình duyệt vào địa chỉ http://localhost:8000.

Tại đây bạn có thể:

• Nhập Username TikTok hoặc link stream.
• Nhấn Start Restream để bắt đầu.
• Xem log trực tiếp từ FFmpeg trong khung Terminal trên Web.

⁠⌨️ 3. Sử dụng CLI (Dòng lệnh)

Nếu bạn muốn chạy script trực tiếp:

• Chế độ Username:

  python src/01_tiktok_to_youtube_restream.py --tiktok-username @user --youtube-stream-key xxxx
  

  Copy
• Chế độ RTMP Bypass (Tiết kiệm CPU nhất):

  python src/01_tiktok_to_youtube_restream.py --rtmp-url "link_flv_tiktok"
  

  Copy

⁠⚙️ 4. Một số lưu ý quan trọng

• Mặc định là Stream Copy: Hệ thống sẽ không encode lại video để tiết kiệm CPU. Nếu YouTube báo lỗi không nhận diện được stream, hãy thử thêm cờ --no-copy.
• Lỗi Access Denied (Windows): Đảm bảo đường dẫn FFMPEG_PATH trong .env trỏ thẳng tới file .exe (ví dụ: C:\\ffmpeg\\bin\\ffmpeg.exe).
• Log: Toàn bộ log được lưu trong thư mục logs/. Bạn nên kiểm tra thường xuyên nếu luồng stream bị ngắt đột ngột.

⁠🛠️ 5. Xử lý lỗi thường gặp

1. WebApp báo Disconnected: Hãy Refresh lại trang web. Dashboard sẽ tự kết nối lại sau mỗi 5 giây.
2. TikTok báo "Channel is not live": Thử cập nhật yt-dlp bằng lệnh pip install -U yt-dlp và đảm bảo streamer thực sự đang phát trực tiếp.
3. CPU quá cao: Kiểm tra xem bạn có đang dùng chế độ Transcode (--no-copy) không. Nếu không cần thiết, hãy tắt nó đi.

📎 Xem thêm tài liệu kỹ thuật:

• 🐳 Tổng quan Docker⁠ — Kiến trúc & các chế độ triển khai.
• 📘 Project Specs⁠ — Phạm vi tính năng, CLI args, Web Dashboard specs.
• ⚙️ Technical Specs⁠ — FFmpeg commands, Backend architecture, WebSocket logic.
• 🔄 Workflow Specs⁠ — Luồng xử lý, Reconnection logic, Web interaction.