### Install Development Dependencies

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/CONTRIBUTING.md

Install the project's development dependencies. uv is recommended for faster installation.

```bash
# Using uv (recommended)
uv pip install --group dev

# Or using pip
pip install -e ".[dev]"
```

--------------------------------

### Install typed-ffmpeg for FFmpeg v6

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/README.md

Install the typed-ffmpeg package that matches your installed FFmpeg version. This example shows how to install the bindings for FFmpeg 6.x.

```bash
ffmpeg -version | head -1        # e.g. ffmpeg version 6.1.1
pip install typed-ffmpeg-v6      # install the matching package
```

--------------------------------

### Install Dependencies

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/examples/typescript-demo/README.md

Installs the necessary project dependencies.

```bash
npm install
```

--------------------------------

### Install and Run Demo Project

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/typescript.md

Instructions to navigate to the demo project directory, install dependencies, and run the development server.

```bash
cd examples/typescript-demo
npm install
npm run dev
```

--------------------------------

### Install typed-ffmpeg with Optional Extras (Python)

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/README.md

Install typed-ffmpeg with optional extras for graph visualization or CLI parsing support. FFmpeg must be installed.

```bash
pip install 'typed-ffmpeg[graph]'          # graph visualization
```

```bash
pip install 'typed-ffmpeg[parse]'          # CLI parsing support
```

```bash
pip install 'typed-ffmpeg-v7[parse]'       # CLI parsing for FFmpeg 7.x
```

--------------------------------

### Install @typed-ffmpeg/v8

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/ts-v8/README.md

Install the core and v8 packages using npm.

```bash
npm install @typed-ffmpeg/core @typed-ffmpeg/v8
```

--------------------------------

### Complex Filter Graph Example (Python)

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/README.md

Demonstrates chaining multiple filters like concat, overlay, and drawbox for advanced video processing. Requires FFmpeg installed.

```python
import ffmpeg.filters
import ffmpeg

# Complex filter graph example
in_file = ffmpeg.input("input.mp4")
overlay_file = ffmpeg.input("overlay.png")

f = (
    ffmpeg.filters
    .concat(
        in_file.trim(start_frame=10, end_frame=20),
        in_file.trim(start_frame=30, end_frame=40),
    )
    .video(0)
    .overlay(overlay_file.hflip())
    .drawbox(x="50", y="50", width="120", height="120", color="red", thickness="5")
    .output(filename="out.mp4")
)
f
```

--------------------------------

### Install @typed-ffmpeg/core

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/ts-core/README.md

Install the core runtime package. This is typically a dependency of version-specific packages.

```bash
npm install @typed-ffmpeg/core
```

--------------------------------

### Clone and install typed-ffmpeg in development

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/core/README.md

Clone the monorepo, navigate to the core package, and install in development mode using uv.

```bash
# Clone monorepo
git clone https://github.com/lucemia/typed-ffmpeg.git
cd typed-ffmpeg

# Install in development mode
cd packages/core
uv pip install -e ".[dev]"

# Run tests
pytest
```

--------------------------------

### Install ffmpeg-core directly

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/core/README.md

For advanced use cases, ffmpeg-core can be installed directly.

```bash
pip install ffmpeg-core
```

--------------------------------

### Install typed-ffmpeg-v8

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/core/README.md

Install any version-specific package to automatically include ffmpeg-core.

```bash
pip install typed-ffmpeg-v8
```

--------------------------------

### Basic Video Processing with TypeScript

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/README.md

Example of scaling a video input and outputting it using typed-ffmpeg TypeScript bindings. Requires FFmpeg installed.

```typescript
import { input } from "@typed-ffmpeg/v8";

const cmd = input("input.mp4")
  .video
  .scale({ w: 1280, h: 720 })
  .output("output.mp4")
  .overwriteOutput()
  .compile();
// => ["-i", "input.mp4", "-filter_complex", "...", "output.mp4"]
```

--------------------------------

### Build and Serve Documentation Locally

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/CONTRIBUTING.md

Install documentation dependencies, build the documentation using mkdocs, and serve it locally for preview.

```bash
# Install docs dependencies
uv pip install --group dev

# Build docs
mkdocs build

# Serve docs locally
mkdocs serve
```

--------------------------------

### Install FFmpeg Flow Editor Dependencies

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/playground/README.md

Clone the repository and install project dependencies using npm. Ensure Node.js and npm are installed.

```bash
git clone https://github.com/lucemia/typed-ffmpeg-playground.git
cd typed-ffmpeg-playground

npm install
```

--------------------------------

### Install Pre-commit Hooks with PreK

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/CONTRIBUTING.md

Install prek hooks for pre-commit. If you previously used pre-commit, uninstall its hooks first.

```bash
# Install hooks (prek included in dev dependencies)
prek install

# Uninstall old hooks first
pre-commit uninstall

# Install prek hooks
prek install
```

--------------------------------

### Install typed-ffmpeg for Specific FFmpeg Versions (Python)

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/README.md

Install typed-ffmpeg bindings for specific FFmpeg versions. Ensure FFmpeg is installed on your system.

```bash
pip install typed-ffmpeg-v5   # FFmpeg 5.x
```

```bash
pip install typed-ffmpeg-v6   # FFmpeg 6.x
```

```bash
pip install typed-ffmpeg-v7   # FFmpeg 7.x
```

```bash
pip install typed-ffmpeg-v8   # FFmpeg 8.x
```

--------------------------------

### Install Development Dependencies with UV

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/README.md

Installs all development dependencies using uv. Dependencies are managed in pyproject.toml and locked in uv.lock.

```bash
uv pip install --group dev
```

--------------------------------

### Install typed-ffmpeg

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/latest/README.md

Install the latest version of typed-ffmpeg using pip. This meta-package ensures you get the most recent stable release.

```bash
pip install typed-ffmpeg
```

--------------------------------

### Install Python Bindings for FFmpeg

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

Install the latest or version-specific typed-ffmpeg Python bindings. Optional extras include graph visualization and CLI parsing.

```bash
pip install typed-ffmpeg

pip install typed-ffmpeg-v5   # FFmpeg 5.x
pip install typed-ffmpeg-v6   # FFmpeg 6.x
pip install typed-ffmpeg-v7   # FFmpeg 7.x
pip install typed-ffmpeg-v8   # FFmpeg 8.x

pip install 'typed-ffmpeg[graph]'         # Graphviz visualization
pip install 'typed-ffmpeg[parse]'         # CLI parsing / compile_as_python()
pip install 'typed-ffmpeg-v7[parse]'      # CLI parsing for FFmpeg 7.x

pip install typed-ffmpeg-compatible       # exposes `typed_ffmpeg` module name
```

--------------------------------

### Install typed-ffmpeg TypeScript Bindings

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/README.md

Install the core TypeScript bindings and bindings for a specific FFmpeg version from npm. FFmpeg must be installed.

```bash
npm install @typed-ffmpeg/core @typed-ffmpeg/v8   # latest FFmpeg bindings
```

--------------------------------

### Flip Video Horizontally (Python)

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/README.md

Example of applying a horizontal flip filter to a video and saving the output. Requires FFmpeg installed.

```python
import ffmpeg

# Flip video horizontally and output
f = (
    ffmpeg
    .input(filename='input.mp4')
    .hflip()
    .output(filename='output.mp4')
)
f
```

--------------------------------

### Google-Style Docstring Example

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/CONTRIBUTING.md

Illustrates the Google-style docstring format required for public APIs, including sections for Args, Returns, Raises, and Example.

```python
def function_name(param1: str, param2: int) -> bool:
    """
    Brief description of function.

    Longer description if needed. Can span multiple lines
    and include details about the function's behavior.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of return value

    Raises:
        ValueError: When param1 is empty

    Example:
        ```python
        result = function_name("test", 42)
        ```

    """
    ...
```

--------------------------------

### Analyze Media File Info (Python)

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/README.md

Use ffmpeg.probe to get information about a media file, such as duration and number of streams. Requires FFmpeg installed.

```python
import ffmpeg

# Analyze a media file
info = ffmpeg.probe("video.mp4")
print(f"Duration: {float(info['format']['duration']):.2f} seconds")
print(f"Streams: {len(info['streams']ınız)}")
```

--------------------------------

### Install typed-ffmpeg-v8

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/v8/README.md

Install the typed-ffmpeg-v8 package using pip. Alternatively, install the generic 'typed-ffmpeg' package which defaults to the latest v8 version.

```bash
pip install typed-ffmpeg-v8
```

```bash
pip install typed-ffmpeg
```

--------------------------------

### Develop FFmpeg Flow Editor

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/playground/README.md

Commands to start the development server, run tests, and build the project for production. These are standard npm scripts.

```bash
npm run dev

npm test

npm run build
```

--------------------------------

### Install TypeScript Bindings for FFmpeg

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

Install the core and version-specific typed-ffmpeg TypeScript bindings for npm.

```bash
npm install @typed-ffmpeg/core @typed-ffmpeg/v8

npm install @typed-ffmpeg/core @typed-ffmpeg/v5
npm install @typed-ffmpeg/core @typed-ffmpeg/v6
npm install @typed-ffmpeg/core @typed-ffmpeg/v7
```

--------------------------------

### Quick Start: Scale and Flip Video

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/typescript.md

Demonstrates basic video manipulation by chaining hflip and scale filters, then outputting to a file. Shows how to compile the FFmpeg command line to a string or an array of arguments.

```typescript
import { input } from "@typed-ffmpeg/v8";

// Scale and flip a video
const cmd = input("input.mp4")
  .video
  .hflip()
  .scale({ w: 1280, h: 720 })
  .output("output.mp4")
  .overwriteOutput();

// Get the FFmpeg command line
console.log(cmd.compileLine());

// Or get arguments as a list
const args = cmd.compile();
```

--------------------------------

### Install typed-ffmpeg with ffmpeg-python (Python)

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/README.md

Install typed-ffmpeg to prevent module name conflicts if ffmpeg-python is also installed. Use 'import typed_ffmpeg as ffmpeg' for imports.

```bash
pip install typed-ffmpeg-compatible
```

--------------------------------

### Install typed-ffmpeg with CLI parsing support

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/README.md

Install typed-ffmpeg with the optional 'parse' extra to enable CLI parsing and the compile_as_python() function. This extra installs version-specific cache data required for reconstructing filter graphs from FFmpeg command lines.

```bash
pip install 'typed-ffmpeg[parse]'
```

--------------------------------

### Uninstall and Install typed-ffmpeg (Latest)

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/migration/v3-to-v4.md

Use these commands to uninstall the old typed-ffmpeg and install the new meta-package, which defaults to FFmpeg 8.x.

```bash
pip uninstall typed-ffmpeg
pip install typed-ffmpeg
```

--------------------------------

### Basic Input/Output Test Example

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/CONTRIBUTING.md

An example of a pytest test case for basic input and output functionality, asserting the compiled FFmpeg command.

```python
def test_input_output():
    """Test basic input/output functionality."""
    stream = ffmpeg.input("input.mp4")
    output = stream.output("output.mp4")
    
    cmd = output.compile()
    assert cmd == ["ffmpeg", "-i", "input.mp4", "output.mp4"]
```

--------------------------------

### Optimized FFmpeg Command Example

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/usage/execute.ipynb

An example of an optimized FFmpeg command generated after removing redundant splits. This command uses trim to extract a 5-second segment from the input video.

```bash
ffmpeg -i input1.mp4 -filter_complex '[0]trim=end=5[s0]' -map '[s0]' tmp.mp4
```

--------------------------------

### Install FFmpeg Versions on macOS

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/development/codegen.md

Install multiple FFmpeg versions side by side using Homebrew for local development.

```bash
brew install ffmpeg@5 ffmpeg@6 ffmpeg@7 ffmpeg      # ffmpeg (no suffix) = latest (v8+)
```

--------------------------------

### Install Package with Optional Parse Extra

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/v4-packages.md

To enable parsing of FFmpeg command lines, install the version package with the `[parse]` extra, which includes version-specific cache data.

```bash
typed-ffmpeg-v7[parse]
```

--------------------------------

### Multi-output Filter Example (Feedback)

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

Demonstrates a filter that produces two output streams. The `feedback` filter is used here, with each output stream processed and saved separately.

```python
import ffmpeg

input1 = ffmpeg.input("input1.mp4")
input2 = ffmpeg.input("input2.mp4")
video, feedout = input1.feedback(input2)

o1 = video.drawtext(text="Main", fontsize=12, x=10, y=10).output("out1.mp4")
o2 = feedout.drawtext(text="Feed", fontsize=12, x=10, y=10).output("out2.mp4")
ffmpeg.merge_outputs(o1, o2).run()
```

--------------------------------

### Check FFmpeg Version and Install Matching Package

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/v4-packages.md

Use this command to check your system's FFmpeg version and then install the corresponding typed-ffmpeg package for exact compatibility.

```bash
# Check your FFmpeg version
ffmpeg -version | head -1
# ffmpeg version 6.1.1 ...

# Install the matching package
pip install typed-ffmpeg-v6
```

--------------------------------

### Install typed-ffmpeg with Graphviz support

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/README.md

Install typed-ffmpeg with the optional 'graph' extra to enable graph visualization using Graphviz. This is useful for debugging and understanding filter graphs.

```bash
pip install 'typed-ffmpeg[graph]'
```

--------------------------------

### Create a New Input Stream

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/usage/basic-api-usage.ipynb

Use `ffmpeg.input` to initiate a stream from a specified file. This is the starting point for most FFmpeg operations.

```python
import ffmpeg

# Create a new input stream
ffmpeg.input("input.mp4")
```

--------------------------------

### Basic FFmpeg Operations (Unchanged API)

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/migration/v3-to-v4.md

These examples demonstrate common FFmpeg operations using the typed-ffmpeg library. The API remains the same between v3 and v4, so existing code should continue to work without modification.

```python
import ffmpeg

# All of these work the same as before
info = ffmpeg.probe("video.mp4")
out = ffmpeg.input("input.mp4").hflip().output("output.mp4")
out.run()
```

--------------------------------

### Specifying Output Options

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/usage/basic-api-usage.ipynb

Configures output options such as start time and duration for the output file.

```APIDOC
## ffmpeg.output with Options

### Description
Creates and configures a new output stream with specified options like start time and duration.

### Method
`input_stream.output(filename, ss=None, t=None, **kwargs)`

### Parameters
#### Path Parameters
- **filename** (string) - Required - The path for the output file.

#### Keyword Arguments
- **ss** (number) - Optional - Specifies the start time in seconds for the output.
- **t** (number) - Optional - Specifies the duration in seconds for the output.

### Request Example
```python
import ffmpeg

ffmpeg.input("input.mp4").output(filename="output.mp4", ss=10, t=20)
```

### Response
#### Success Response
Returns an `OutputStream` object configured with the specified output options.
```

--------------------------------

### Source Filters (e.g., Color)

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

Source filters do not require an input stream and can generate media directly. This example creates a red background video.

```python
import ffmpeg

# Source filters (no input stream required)
( 
    ffmpeg.sources.color(color="red", size="hd1080")
    .output("red_bg.mp4", t=5)
    .run()
)
```

--------------------------------

### Uninstall and Install Specific FFmpeg Version Package

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/migration/v3-to-v4.md

Uninstall the old typed-ffmpeg and install a specific versioned package to match your system's FFmpeg version.

```bash
pip uninstall typed-ffmpeg

# Choose the package that matches your system FFmpeg
pip install typed-ffmpeg-v5   # FFmpeg 5.x
pip install typed-ffmpeg-v6   # FFmpeg 6.x
pip install typed-ffmpeg-v7   # FFmpeg 7.x
pip install typed-ffmpeg-v8   # FFmpeg 8.x
```

--------------------------------

### Analyze Media Files with ffmpeg.probe()

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

Use ffmpeg.probe() to get media file information as a dictionary or ffmpeg.probe_obj() for a typed dataclass. Handle potential FFMpegExecuteError for missing files.

```python
import ffmpeg
from ffmpeg.exceptions import FFMpegExecuteError

# --- probe(): dict interface ---
info = ffmpeg.probe("video.mp4")

print(f"Format : {info['format']['format_name']}")
print(f"Duration: {float(info['format']['duration']):.2f}s")
print(f"Bitrate : {int(info['format']['bit_rate']) // 1000} kbps")

for stream in info["streams"]:
    if stream["codec_type"] == "video":
        print(f"Video: {stream['codec_name']} {stream['width']}x{stream['height']}")
    elif stream["codec_type"] == "audio":
        print(f"Audio: {stream['codec_name']} {stream['sample_rate']} Hz")
```

```python
import ffmpeg
from ffmpeg.exceptions import FFMpegExecuteError

# Extended probing options
full = ffmpeg.probe(
    "video.mp4",
    show_chapters=True,
    show_programs=True,
    show_frames=False,
    loglevel="quiet",
    timeout=30,
)
```

```python
import ffmpeg
from ffmpeg.exceptions import FFMpegExecuteError

# --- probe_obj(): dataclass interface (dot-notation access) ---
obj = ffmpeg.probe_obj("video.mp4")
print(f"Streams : {len(obj.streams.stream)}")
for s in obj.streams.stream:
    if s.codec_type == "video":
        print(f"  Video: {s.codec_name} {s.width}x{s.height}")
```

```python
import ffmpeg
from ffmpeg.exceptions import FFMpegExecuteError

# --- Error handling ---
try:
    ffmpeg.probe("missing.mp4")
except FFMpegExecuteError as e:
    print(f"ffprobe failed (exit {e.retcode}): {e.stderr.decode()}")
```

--------------------------------

### Adding Input Options

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/usage/basic-api-usage.ipynb

Specifies additional options for the input stream, such as start time (`ss`) and duration (`t`).

```APIDOC
## ffmpeg.input with Options

### Description
Creates a new input stream with specific options like start time and duration.

### Method
`ffmpeg.input(filename, ss=None, t=None, **kwargs)`

### Parameters
#### Path Parameters
- **filename** (string) - Required - The path to the input file.

#### Keyword Arguments
- **ss** (number) - Optional - Specifies the start time in seconds.
- **t** (number) - Optional - Specifies the duration in seconds.

### Request Example
```python
import ffmpeg

ffmpeg.input("input.mp4", ss=10, t=20)
```

### Response
#### Success Response
Returns an `AVStream` object representing the input stream with specified options.
```

--------------------------------

### Basic Video Processing with typed-ffmpeg

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/latest/README.md

Demonstrates a simple video processing task: flipping a video horizontally and saving it. Requires FFmpeg to be installed on the system.

```python
import ffmpeg

# Input and output
input_file = ffmpeg.input("input.mp4")
output_file = input_file.hflip().output("output.mp4")
output_file.run()
```

--------------------------------

### Basic FFmpeg Operations with typed-ffmpeg

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/v4-packages.md

Demonstrates basic usage of the typed-ffmpeg library for probing files and building/running filter graphs. The `ffmpeg` namespace is consistent across all installed packages.

```python
import ffmpeg

# Probe a file
info = ffmpeg.probe("video.mp4")

# Build and run a filter graph
(
    ffmpeg.input("input.mp4")
    .hflip()
    .output("output.mp4")
    .run()
)
```

--------------------------------

### Basic Media File Analysis with probe()

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/usage/probe.ipynb

Use the `probe()` function to get media file information as a Python dictionary. Access stream details like codec type by indexing the returned dictionary.

```python
import ffmpeg

# Get basic information about a media file
info = ffmpeg.probe("Digraph.gv.png")
print(info["streams"][0]["codec_type"])
info
```

--------------------------------

### Specify Output Options

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/usage/basic-api-usage.ipynb

Configure output options such as start time (`ss`) and duration (`t`) directly within the `ffmpeg.output` function to control the output segment.

```python
import ffmpeg

# Create and configure a new output stream
ffmpeg.input("input.mp4").output(
    filename="output.mp4", ss=10, t=20
)  # Output starting at 10 seconds with a duration of 20 seconds
```

--------------------------------

### Compile FFmpeg Command to String

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/usage/execute.ipynb

Get the FFmpeg command as a single string. This is an alternative to compiling into a list, useful for logging or displaying the full command.

```python
# Alternatively, get the command line as a single string
command_string = f.compile_line()
command_string
```

--------------------------------

### Install Specific Typed-FFmpeg Version

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/version-differences.md

Pin to a specific package version if your code uses filters or codecs removed in later versions. Use `typed-ffmpeg-v7` for access to scale_vaapi, drawtext, etc., or `typed-ffmpeg-v8` for the latest version including macOS VideoToolbox codecs.

```bash
pip install typed-ffmpeg-v7   # keeps access to scale_vaapi, drawtext, etc.
```

```bash
pip install typed-ffmpeg-v8   # latest, macOS VideoToolbox codecs included
```

--------------------------------

### Run Linting and Formatting with PreK and Ruff

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/CONTRIBUTING.md

Apply code formatting and linting using prek and Ruff. Ruff is recommended for its speed.

```bash
# Using prek (recommended - 2-10x faster)
prek run --all-files

# Or run individual tools
ruff check src/
ruff format src/
```

--------------------------------

### Run Demo

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/examples/typescript-demo/README.md

Compiles the TypeScript code and executes the demo, printing generated FFmpeg commands.

```bash
npm run dev
```

--------------------------------

### Overlay and Multiple Outputs (TypeScript)

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

Demonstrates overlaying a logo onto a main video and creating multiple output files at different resolutions from a single input. Utilizes FilterNode and mergeOutputs.

```typescript
import { InputNode, FilterNode, OutputNode, StreamType, mergeOutputs } from "@typed-ffmpeg/v8";

// Overlay logo on main video
const main   = new InputNode("main.mp4");
const logo   = new InputNode("logo.png");
const overlay = new FilterNode("overlay", [main.video, logo.video], { x: 10, y: 10 },
  [StreamType.Video, StreamType.Video], [StreamType.Video]
);
const logoCmd = new OutputNode([overlay.video(0)], "with_logo.mp4").stream().overwriteOutput();

// Multiple outputs at different resolutions from the same input
const src = new InputNode("input.mp4");
const hd  = new FilterNode("scale", [src.video], { w: 1920, h: 1080 }, [StreamType.Video], [StreamType.Video]);
const sd  = new FilterNode("scale", [src.video], { w: 1280, h: 720  }, [StreamType.Video], [StreamType.Video]);

const multiCmd = mergeOutputs(
  new OutputNode([hd.video(0)], "1080p.mp4").stream(),
  new OutputNode([sd.video(0)], "720p.mp4").stream(),
);
console.log(multiCmd.compileLine());
// => 'ffmpeg -i input.mp4 -filter_complex "[0:v]scale=w=1920:h=1080[s0];[0:v]scale=w=1280:h=720[s1]" -map "[s0]" 1080p.mp4 -map "[s1]" 720p.mp4'
```

--------------------------------

### Codec Options Support

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/usage/basic-api-usage.ipynb

Illustrates how to specify codec options for input and output nodes, including encoder options like CRF, preset, and tune. The pix_fmt is set to 'yuv420p' for compatibility.

```python
import ffmpeg

input1 = ffmpeg.input("input1")
input1.output(
    filename="out.mp4",
    encoder_options=ffmpeg.codecs.encoders.libx264(
        crf=18, preset="slow", tune="flim", aq_strength=1.8, mbtree=0
    ),
    pix_fmt="yuv420p",
)
```

--------------------------------

### Check FFmpeg Version

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/migration/v3-to-v4.md

Run this command in your terminal to check your installed FFmpeg version. This helps determine which typed-ffmpeg package to install.

```bash
ffmpeg -version | head -1
```

--------------------------------

### Generate Bindings for FFmpeg 7 Locally

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/development/codegen.md

Generate bindings for a specific FFmpeg version by setting the PATH to its binary directory.

```bash
PATH="$(brew --prefix ffmpeg@7)/bin:$PATH" \
  python -m scripts.code_gen.cli generate --outpath packages/v7/src/ffmpeg --rebuild
```

--------------------------------

### Run Pre-commit Hooks

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/CONTRIBUTING.md

Execute all configured pre-commit hooks on all files. Use this to ensure your changes meet the project's quality standards before committing.

```bash
prek run --all-files
```

```bash
prek run ruff
```

```bash
git commit --no-verify -m "message"
```

--------------------------------

### Generate Bindings with Specific FFmpeg Binary Path

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/development/codegen.md

Generate bindings by specifying the FFmpeg binary path directly using the --ffmpeg-binary flag.

```bash
python -m scripts.code_gen.cli generate \
  --outpath packages/v7/src/ffmpeg \
  --ffmpeg-binary /usr/local/opt/ffmpeg@7/bin/ffmpeg \
  --rebuild
```

--------------------------------

### Run Tests for typed-ffmpeg v5

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/tests-shared/README.md

Installs the typed-ffmpeg v5 package and runs shared tests using pytest.

```bash
uv sync --package typed-ffmpeg-v5
pytest packages/tests-shared -v
```

--------------------------------

### Run Tests for typed-ffmpeg v8

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/tests-shared/README.md

Installs the typed-ffmpeg v8 package and runs shared tests using pytest.

```bash
uv sync --package typed-ffmpeg-v8
pytest packages/tests-shared -v
```

--------------------------------

### CLI Command: Generate Bindings

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/development/codegen.md

Generate bindings, automatically detecting the FFmpeg version from the binary on PATH. Use --rebuild to ignore cache and --ffmpeg-binary to specify a path.

```bash
python -m scripts.code_gen.cli generate --outpath <path> [--rebuild] [--ffmpeg-binary <path>]
```

--------------------------------

### Clone the Repository

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/CONTRIBUTING.md

Clone the typed-ffmpeg repository to your local machine. Navigate into the cloned directory.

```bash
git clone https://github.com/YOUR_USERNAME/typed-ffmpeg.git
cd typed-ffmpeg
```

--------------------------------

### Trim Video and Add Text Watermark

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/usage/complex-filtering.ipynb

Apply trimming and drawtext filters to a video stream. Ensure FFmpeg is installed and accessible in your PATH.

```python
%xmode Minimal
import ffmpeg

# Initialize the input stream from a video file
input_stream = ffmpeg.input("input.mp4")

# Apply trimming and drawtext filters, then output to a new file
(
    input_stream.trim(start=10, end=20)
    .drawtext(text="Hello World", fontsize=12, x=10, y=10)
    .output(filename="output.mp4")
)
```

--------------------------------

### Concatenate Video Clips with `ffmpeg.filters.concat()`

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

The `concat` filter concatenates multiple video or audio streams. This example concatenates two trimmed clips.

```python
import ffmpeg
from ffmpeg.filters import concat

# concat: concatenate two trimmed clips
in_file = ffmpeg.input("input.mp4")
( 
    concat(
        in_file.trim(start_frame=10, end_frame=20),
        in_file.trim(start_frame=30, end_frame=40),
    )
    .video(0)
    .output("concatenated.mp4")
    .run()
)
```

--------------------------------

### Chained Audio Filters

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

Audio filters are available as typed methods on `AudioStream` objects. This example applies volume adjustment and an audio fade effect.

```python
import ffmpeg

# Normalize volume, add fade in/out
( 
    ffmpeg.input("input.mp4").audio
    .volume(volume=0.5)
    .afade(type="in", start_time=0, duration=2)
    .output("quiet_fade.mp3")
    .run()
)
```

--------------------------------

### Import core runtime modules

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/core/README.md

Import FilterNode, Stream, and compile_as_list for advanced usage of the core runtime.

```python
from ffmpeg_core.dag import FilterNode, Stream
from ffmpeg_core.compile import compile_as_list
```

--------------------------------

### Map Multiple Inputs to a Single Output

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/usage/basic-api-usage.ipynb

Demonstrates mapping multiple input files to a single output file using the ffmpeg.output function.

```python
import ffmpeg

# Chain input and output operations
(ffmpeg.input("input1.mp4").output(ffmpeg.input("input2.mp3"), filename="output.mp4"))
```

--------------------------------

### Create FFmpeg Input Stream (Python)

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

Use `ffmpeg.input()` to create an input stream node. Accepts standard FFmpeg input options and allows selection of specific sub-streams by type or index.

```python
import ffmpeg

# Basic input
stream = ffmpeg.input("input.mp4")

# Input with options: seek to 10 s, limit duration to 20 s
stream = ffmpeg.input("input.mp4", ss=10, t=20)

# Select specific sub-streams
video = ffmpeg.input("input.mp4").video          # VideoStream (all video tracks)
audio = ffmpeg.input("input.mp4").audio          # AudioStream (all audio tracks)
subs  = ffmpeg.input("input.mp4").subtitle       # subtitle track

# Select by index
v0 = ffmpeg.input("input.mp4").video_stream(0)   # first video track → -map 0:v:0
a0 = ffmpeg.input("input.mp4").audio_stream(0)   # first audio track → -map 0:a:0

# Inspect the generated command
ffmpeg.input("input.mp4", ss=10).video.output("out.mp4").compile_line()
# => 'ffmpeg -ss 10 -i input.mp4 -map 0:v out.mp4'
```

--------------------------------

### Importing Filters in v4

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/migration/v3-to-v4.md

In v4, after installing a specific versioned package (e.g., `typed-ffmpeg-v6`), import filters directly from the top-level `ffmpeg` namespace, not from version-specific submodules.

```python
# v4 style: install typed-ffmpeg-v6, then import normally
from ffmpeg.filters import concat
```

--------------------------------

### Dependency Pinning for Stability

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/migration/v3-to-v4.md

To ensure stability during the alpha phase of v4 packages, pin your dependency to a specific version range. This example shows how to pin `typed-ffmpeg-v6`.

```pip
typed-ffmpeg-v6>=1.0.0a1,<2.0
```

--------------------------------

### Define Custom Filter with Positional Arguments in ffmpeg-python

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/faq.md

In ffmpeg-python, custom filters can accept arguments positionally. This example shows a 'crop' filter with positional arguments.

```python
ffmpeg.input("in.mp4")
    .filter('crop', 'in_w-2*10', 'in_h-2*20')
```

--------------------------------

### Multi-input / Multi-output Filters

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

typed-ffmpeg supports filters that accept or produce multiple streams, with runtime and static type validation. Examples include `concat`, `feedback`, and `split`.

```APIDOC
## Multi-input / Multi-output Filters

### Description
typed-ffmpeg supports filters that accept or produce multiple streams, with runtime and static type validation.

### Method
Used with filters like `concat`, `feedback`, and `split`.

### Request Example
```python
import ffmpeg

# concat: concatenate two trimmed clips
in_file = ffmpeg.input("input.mp4")
(ffmpeg.filters.concat(
    in_file.trim(start_frame=10, end_frame=20),
    in_file.trim(start_frame=30, end_frame=40),
)
    .video(0)
    .output("concatenated.mp4")
    .run()
)

# feedback filter → two output streams
input1 = ffmpeg.input("input1.mp4")
input2 = ffmpeg.input("input2.mp4")
video, feedout = input1.feedback(input2)

o1 = video.drawtext(text="Main", fontsize=12, x=10, y=10).output("out1.mp4")
o2 = feedout.drawtext(text="Feed", fontsize=12, x=10, y=10).output("out2.mp4")
ffmpeg.merge_outputs(o1, o2).run()

# split: explicitly split one stream into N
input1 = ffmpeg.input("input.mp4")
split  = input1.split(outputs=2)
v0 = split.video(0)
v1 = split.video(1)
# accessing split.video(2) raises: FFMpegValueError: index 2 out of range for 2 outputs
```

### Response
(No specific response details provided in the source)
```

--------------------------------

### ffmpeg.probe() / ffmpeg.probe_obj()

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

Analyze media files using FFprobe, retrieving detailed information as either a dictionary or a typed dataclass object.

```APIDOC
## `ffmpeg.probe()` / `ffmpeg.probe_obj()` — Media file analysis

Wraps FFmpeg's `ffprobe` utility. `probe()` returns a dict; `probe_obj()` returns a typed dataclass.

```python
import ffmpeg
from ffmpeg.exceptions import FFMpegExecuteError

# --- probe(): dict interface ---
info = ffmpeg.probe("video.mp4")

print(f"Format : {info['format']['format_name']}")
print(f"Duration: {float(info['format']['duration']):.2f}s")
print(f"Bitrate : {int(info['format']['bit_rate']) // 1000} kbps")

for stream in info["streams"]:
    if stream["codec_type"] == "video":
        print(f"Video: {stream['codec_name']} {stream['width']}x{stream['height']}")
    elif stream["codec_type"] == "audio":
        print(f"Audio: {stream['codec_name']} {stream['sample_rate']} Hz")

# Extended probing options
full = ffmpeg.probe(
    "video.mp4",
    show_chapters=True,
    show_programs=True,
    show_frames=False,
    loglevel="quiet",
    timeout=30,
)

# --- probe_obj(): dataclass interface (dot-notation access) ---
obj = ffmpeg.probe_obj("video.mp4")
print(f"Streams : {len(obj.streams.stream)}")
for s in obj.streams.stream:
    if s.codec_type == "video":
        print(f"  Video: {s.codec_name} {s.width}x{s.height}")

# --- Error handling ---
try:
    ffmpeg.probe("missing.mp4")
except FFMpegExecuteError as e:
    print(f"ffprobe failed (exit {e.retcode}): {e.stderr.decode()}")
```
```

--------------------------------

### Chained Video Filters

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

All FFmpeg video filters are available as typed methods on `VideoStream` objects. This example demonstrates chaining trim, drawtext, scale, and hflip filters.

```python
import ffmpeg

# Trim, watermark, scale, flip
( 
    ffmpeg.input("input.mp4")
    .trim(start=10, end=20)          # trim to [10s, 20s]
    .drawtext(text="Hello", fontsize=24, x=10, y=10)
    .scale(w=1280, h=720)
    .hflip()
    .output("output.mp4")
    .run()
)
```

--------------------------------

### Core Exports

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/typescript.md

These are the fundamental building blocks for creating FFmpeg commands with typed-ffmpeg.

```APIDOC
## Core Exports (`@typed-ffmpeg/core`)

### Description
Provides core types and functions for building FFmpeg command graphs.

### Exports
- `InputNode`: Represents an FFmpeg input (`-i`).
- `OutputNode`: Represents an FFmpeg output.
- `FilterNode`: Represents a filter in the graph.
- `VideoStream` / `AudioStream`: Typed stream references.
- `mergeOutputs()`: Combine multiple outputs into one command.
- `compile()` / `compileAsList()`: Compile a DAG to FFmpeg arguments.
- `validate()` / `fixGraph()`: Validate and auto-correct filter graphs.
- `run()` / `runAsync()`: Execute FFmpeg commands.
- `StreamType`: Enum: `Video`, `Audio`.
```

--------------------------------

### Compile FFmpeg Command (Python)

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

Use `.compile()` to get FFmpeg arguments as a list or `.compile_line()` for a shell string, without executing the command. Useful for debugging and integration.

```python
import ffmpeg

f = (
    ffmpeg.input("input.mp4")
    .trim(start=10, end=20)
    .drawtext(text="Hello World", fontsize=12, x=10, y=10)
    .output(filename="output.mp4")
)

# As a list (suitable for subprocess.run)
f.compile()
# => ['ffmpeg', '-i', 'input.mp4',
#     '-filter_complex',
#     "[0]trim=start=10:end=20[s0];[s0]drawtext=text=Hello World:fontsize=12:x=10:y=10[s1]",
#     '-map', '[s1]', 'output.mp4']

# As a shell string
f.compile_line()
```

--------------------------------

### Compile FFmpeg Command to Argument List

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/typescript.md

Shows how to compile a constructed FFmpeg command into an array of strings, suitable for passing as arguments to a process. This is an alternative to compiling to a single command line string.

```typescript
import { input } from "@typed-ffmpeg/v8";

const cmd = input("input.mp4")
  .video
  .scale({ w: 640, h: 480 })
  .output("small.mp4")
  .overwriteOutput();

// Get arguments as string[]
const args: string[] = cmd.compile();
// => ["-i", "input.mp4", "-filter_complex", "...", "small.mp4", "-y"]
```

--------------------------------

### Add Input Options to Stream

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/usage/basic-api-usage.ipynb

Specify additional options like start time (`ss`) and duration (`t`) directly within the `ffmpeg.input` function to control the input stream segment.

```python
import ffmpeg

# Create a new input stream with specific options
ffmpeg.input("input.mp4", ss=10, t=20)  # Start at 10 seconds and last for 20 seconds
```

--------------------------------

### Visualize FFmpeg Filter Graph with `.view()`

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

Renders the filter graph as a PNG/SVG using Graphviz. Requires `pip install 'typed-ffmpeg[graph]'`. In Jupyter notebooks, the graph is displayed inline automatically.

```python
import ffmpeg

f = (
    ffmpeg.input("input.mp4")
    .trim(start=10, end=20)
    .drawtext(text="Hello World", fontsize=12, x=10, y=10)
    .output(filename="output.mp4")
)

# Renders and opens Digraph.gv.png
f.view()
```

```python
# In Jupyter notebooks the graph is displayed inline automatically
f   # displays SVG in a notebook cell
```

--------------------------------

### List All CoreImage Filters

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/src/scripts/parse_docs/tests/test_helpers/coreimage.html

Use `list_filters=true` to see all available filters and their options, including value ranges and defaults. This is essential for understanding filter capabilities before applying them.

```ffmpeg
list_filters=true
```

--------------------------------

### Complex FFmpeg Filter Graph with typed-ffmpeg

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/v8/README.md

Illustrates creating a complex filter graph involving concatenating trimmed segments of a video and overlaying a flipped image. Requires FFmpeg 8.x installed.

```python
in_file = ffmpeg.input("input.mp4")
overlay_file = ffmpeg.input("overlay.png")

output = (
    ffmpeg.filters
    .concat(
        in_file.trim(start_frame=10, end_frame=20),
        in_file.trim(start_frame=30, end_frame=40),
    )
    .video(0)
    .overlay(overlay_file.hflip())
    .output("out.mp4")
)

output.run()
```

--------------------------------

### Complex Filter Graph with typed-ffmpeg

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/packages/latest/README.md

Illustrates how to construct a complex filter graph involving concatenating trimmed video segments, overlaying a flipped image, and outputting the result. Ensure FFmpeg is installed.

```python
import ffmpeg

in_file = ffmpeg.input("input.mp4")
overlay_file = ffmpeg.input("overlay.png")

output = (
    ffmpeg.filters
    .concat(
        in_file.trim(start_frame=10, end_frame=20),
        in_file.trim(start_frame=30, end_frame=40),
    )
    .video(0)
    .overlay(overlay_file.hflip())
    .output("out.mp4")
)

output.run()
```

--------------------------------

### ffmpeg.output() / .output()

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

Configures an FFmpeg output node from one or more streams. Accepts standard FFmpeg output options as keyword arguments.

```APIDOC
## ffmpeg.output() / .output()

### Description
Configures an FFmpeg output node from one or more streams. Accepts all standard FFmpeg output options as keyword arguments.

### Method
`ffmpeg.output(*streams, filename, **options)` or `stream.output(stream, filename, **options)`

### Parameters
#### Streams
- `*streams` (AVStream or list of AVStream) - Required - One or more input streams to be output.
- `filename` (string) - Required - The output file path or stream.

#### Keyword Arguments (Options)
- **vcodec** (string) - Optional - Specify the video codec.
- **t** (number) - Optional - Trim the output to a specific duration.

### Request Example
```python
import ffmpeg

# Single input -> output
ffmpeg.input("input.mp4").output(filename="output.mp4")

# With output options: encode with libx264, trim to 30 s
ffmpeg.input("input.mp4").output(filename="out.mp4", vcodec="libx264", t=30)

# Two inputs merged into one output file
input1 = ffmpeg.input("video.mp4")
input2 = ffmpeg.input("audio.mp3")
ffmpeg.output(input1, input2, filename="combined.mp4")

# Chain syntax: attach a second input to an existing output call
( ffmpeg.input("video.mp4")
  .output(ffmpeg.input("audio.mp3"), filename="combined.mp4")
)
```

### Response Example
```python
# Inspect the generated command
print(ffmpeg.input("input.mp4").output(filename="out.mp4", vcodec="libx264", t=30).compile_line())
# => 'ffmpeg -i input.mp4 -vcodec libx264 -t 30 out.mp4'
```
```

--------------------------------

### ffmpeg.input()

Source: https://context7.com/lucemia/typed-ffmpeg/llms.txt

Creates an AVStream node representing an FFmpeg input. It accepts standard FFmpeg input options as keyword arguments and allows selection of specific sub-streams.

```APIDOC
## ffmpeg.input()

### Description
Creates an `AVStream` node representing an FFmpeg `-i` input. Accepts all standard FFmpeg input options as keyword arguments.

### Method
`ffmpeg.input(filename, **options)`

### Parameters
#### Path Parameters
- **filename** (string) - Required - The input file path or stream.

#### Keyword Arguments (Options)
- **ss** (number) - Optional - Seek to a specific time in seconds.
- **t** (number) - Optional - Limit the duration of the input.

### Stream Selection
- `.video`: Selects all video streams.
- `.audio`: Selects all audio streams.
- `.subtitle`: Selects all subtitle streams.
- `.video_stream(index)`: Selects the video stream at the specified index.
- `.audio_stream(index)`: Selects the audio stream at the specified index.

### Request Example
```python
import ffmpeg

# Basic input
stream = ffmpeg.input("input.mp4")

# Input with options: seek to 10 s, limit duration to 20 s
stream = ffmpeg.input("input.mp4", ss=10, t=20)

# Select specific sub-streams
video = ffmpeg.input("input.mp4").video
audio = ffmpeg.input("input.mp4").audio

# Select by index
v0 = ffmpeg.input("input.mp4").video_stream(0)
a0 = ffmpeg.input("input.mp4").audio_stream(0)
```

### Response Example
```python
# Inspect the generated command
print(ffmpeg.input("input.mp4", ss=10).video.output("out.mp4").compile_line())
# => 'ffmpeg -ss 10 -i input.mp4 -map 0:v out.mp4'
```
```

--------------------------------

### Execute FFmpeg Command

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/usage/execute.ipynb

Run the defined FFmpeg command. This method executes the FFmpeg process and handles the input and output streams as specified.

```python
# Execute the FFmpeg command
f.run()
```

--------------------------------

### Compile FFmpeg Command to List

Source: https://github.com/lucemia/typed-ffmpeg/blob/main/docs/usage/execute.ipynb

Compile the FFmpeg command into a list of strings, representing the command and its arguments. Useful for debugging and verification.

```python
# Compile the FFmpeg command into a list format
command_list = f.compile()
command_list
```