Skip to content

README.md

Latest commit

 

History

History
178 lines (128 loc) · 4.77 KB

README.md

File metadata and controls

178 lines (128 loc) · 4.77 KB

Pixel Labler / FFmpeg Crop Tool

A comprehensive toolkit for video processing, clipping, transcribing, downloading, and uploading.

Prerequisites

  • Python 3.9+
  • uv (Fast Python package installer and resolver)
  • FFmpeg (Must be installed and strictly in your system PATH)
  • Ollama (Optional, for local AI translation)

Installation

This project uses uv for dependency management.

  1. Install dependencies: 
    uv sync

1. Monitor & Auto-Downloader (monitor.py)

Automatically monitors a Twitch channel for new VODs and triggers the download pipeline.

Usage

# Run manually
uv run monitor.py

# Setup Cron (e.g., check every hour)
0 * * * * cd /path/to/repo && uv run monitor.py >> monitor.log 2>&1

Features

  • Smart Tracking: Uses memory.txt to track the last processed VOD timestamp.
  • Auto-Trigger: Calls twitch_download.py immediately when a new VOD is found.
  • Configurable:
    • --channel_url: Default https://www.twitch.tv/zackrawrr.
    • --memory_file: File to store state.

2. Twitch Downloader (twitch_download.py)

Download VODs from Twitch using yt-dlp and chat_utils.

Usage

# Download entire VOD
uv run twitch_download.py "TWITCH_VOD_URL"

# Download specific range (e.g., from minute 10 to 30)
uv run twitch_download.py "TWITCH_VOD_URL" --start_min 10 --duration_min 20

Features

  • Optimized Video: Downloads 480p (or best ≤ 480p) to original.mp4.
  • Slicing Support: Can download specific time ranges without fetching the entire VOD.
  • Chat Download: Automatically fetches full (or sliced) Twitch chat logs using the GQL API.
  • Direct Audio: Extracts audio directly to audio.mp4.
  • Auto-Pipeline:
    1. Downloads Video, Audio, and Chat.
    2. Transcribes Audio (generating transcript.srt).
    3. Triggers N8N workflow (analyze).

Options

  • --root_dir: Base directory for downloads.
  • --audio / --no-audio: Toggle audio extraction.
  • --start_min: Start time in minutes.
  • --duration_min: Duration to download in minutes.

3. Chat Downloader (chat_utils.py)

A robust Twitch chat downloader using the modern GQL API.

Usage

# Download entire chat
uv run python chat_utils.py "TWITCH_VOD_URL" chat.json

# Download specific range (e.g., first hour)
uv run python chat_utils.py "TWITCH_VOD_URL" chat.json 0 60

Features

  • GQL Powered: Uses Twitch's internal GraphQL API for high reliability.
  • Range Support: Can jump to any timestamp using --start_min and --duration_min.
  • Format Compatible: Produces a structured JSON chat log.

4. YouTube Downloader (yt_download.py)

Download videos from YouTube.

Usage

uv run yt_download.py "YOUTUBE_URL"

Features

  • Auto-Folder: Creates a folder named after the video title (safe_title/).
  • Metadata: Generates metadata.md.
  • Audio Extraction: Automatically extracts audio to audio.mp4.
  • Auto-Transcribe: Automatically transcribes Shorts (< 180s).

5. Transcription Tool (transcript.py)

Generate SRT subtitles using AssemblyAI (default) or faster-whisper, with translation support using Google Translate (default) or Ollama.

Usage

uv run transcript.py /path/to/video.mp4 --zh_output "zh.srt"

Features

  • Engines:
    • assemblyai (Default): Requires ASSEMBLYAI_API_KEY.
    • faster_whisper: Local, GPU/CPU supported.
  • Translation:
    • google (Default): Uses deep-translator (Google Translate).
    • ollama: Uses local LLM (e.g., Llama 3).
  • Splitting: Can split long SRTs into hourly chunks (--split-by-hour).

Options

  • --engine: assemblyai (default) or faster_whisper.
  • --translation_engine: google (default) or ollama.
  • --zh_output: Path for translated Chinese SRT.
  • --split-by-hour: Enable splitting transcript.srt into transcript-chunked/.

6. Generic Translator (translate.py)

Simple CLI tool to translate text/files using Google Translate.

Usage

# Translate text string
uv run translate.py "Hello World" -t zh-TW

# Translate file content
uv run translate.py path/to/file.txt

7. Batch Clipper (crop.py)

Process a long video into multiple clips based on a list.

Usage

uv run crop.py /path/to/RootFolder

Features

  • Formats: Generates Vertical Stacked (9:16), Cam, Screen, Raw, and Audio.
  • Watermark: Adds @StreamFlash watermark.
  • Auto-Transcribe/Translate: Generates transcript.srt and zh.srt for clips.
  • Input: Reads crop_info.csv (Shorts No, Start, End, Summary, Title, Hook).

8. Interactive Crop UI (main.py)

Visual tool to determine FFmpeg crop parameters.

Usage

uv run main.py