Skip to content

Latest commit

 

History

History
113 lines (83 loc) · 3.96 KB

CLAUDE.md

File metadata and controls

113 lines (83 loc) · 3.96 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

FastFlix is a Python GUI application for video encoding/transcoding using PySide6 (Qt6). It wraps FFmpeg and supports 25+ encoder backends including x264, x265, AV1 variants, VP9, VVC, and hardware encoders (NVIDIA NVEncC, Intel QSVEncC, AMD VCEEncC).

Requirements: Python 3.13+, FFmpeg 4.3+ (5.0+ recommended)

Build & Development Commands

# Install dependencies
uv sync --frozen

# Lint and format
uv run ruff check              # Check for violations
uv run ruff check --fix        # Auto-fix issues
uv run ruff format             # Format code

# Run tests
uv run pytest tests -v
PYTEST_QT_API=pyside6 uv run pytest tests -v  # Linux with Qt

# Run specific test file
uv run pytest tests/encoders/test_hevc_x265_command_builder.py -v

# Run the application
python -m fastflix

# Build executables
uv run pyinstaller FastFlix_Windows_OneFile.spec
uv run pyinstaller FastFlix_Nix_OneFile.spec

Code Style

  • Line length: 120 characters
  • Double quotes for strings
  • Ruff for linting and formatting (Black-compatible)
  • Type hints via Pydantic models

Architecture

Multi-Process Design

  • Main process (entry.py): Sets up queues and spawns worker subprocess
  • GUI process (application.py): Qt application (prevents UI blocking)
  • Worker process (conversion_worker.py): Processes conversion queue
  • Queue communication between processes for status/logging

Encoder Plugin System

Each encoder lives in fastflix/encoders/{encoder_name}/ with:

  • __init__.py: Encoder metadata/registration
  • command_builder.py: Implements build(fastflix) -> List[Command]
  • Settings model in models/encode.py (Pydantic)
  • UI panel in widgets/panels/{encoder_name}/

Key Modules

Module Purpose
flix.py Core FFmpeg/FFprobe interaction
widgets/main.py Main GUI window
models/config.py Configuration management
models/encode.py Encoder settings models
encoders/common/helpers.py Shared command building utilities

Data Flow

  1. User loads video → parse() via FFprobe
  2. Encoding options set → Pydantic model validation
  3. Video queued → Added to conversion_list
  4. Worker processes → Encoder's build() generates FFmpeg commands
  5. command_runner.py executes → Progress streamed to GUI

Adding a New Encoder

  1. Create directory: fastflix/encoders/{encoder_name}/
  2. Add settings class to models/encode.py
  3. Implement command_builder.py with build(fastflix) -> List[Command]
  4. Create UI panel in widgets/panels/{encoder_name}/
  5. Add tests in tests/encoders/test_{encoder_name}_command_builder.py

Configuration

  • Config file: ~/.config/FastFlix/fastflix.yaml
  • Portable mode: Place fastflix.yaml in app directory
  • Environment overrides: FF_FFMPEG, FF_FFPROBE, FF_HDR10PLUS, FF_CONFIG

FFmpeg Command Research

IMPORTANT: Always research FFmpeg commands online before implementing or modifying encoder command builders. FFmpeg options and filter syntax can change between versions.

Resources to consult:

Key considerations:

  • Filter order matters (e.g., scale before palettegen for GIFs)
  • Use appropriate scale flags (lanczos/bicubic over bilinear)
  • Verify filter_complex syntax for multi-input/output chains
  • Check encoder-specific options in official docs

Changelog

IMPORTANT: Always update the CHANGES file when making significant additions or bug fixes during a session. Add entries under the current version section at the top of the file using the format:

  • * Adding {feature description} for new features
  • * Fixing {bug description} for bug fixes

Branching

  • master: Release branch
  • develop: Development branch (PRs merge here)