Metadata-Version: 2.4
Name: cjm-ffmpeg-utils
Version: 0.0.2
Summary: Audio/video processing utilities with FFmpeg: extraction, conversion, metadata handling, and progress bars.
Home-page: https://github.com/cj-mills/cjm-ffmpeg-utils
Author: Christian J. Mills
Author-email: 9126128+cj-mills@users.noreply.github.com
License: Apache Software License 2.0
Keywords: nbdev jupyter notebook python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastcore
Requires-Dist: tqdm
Requires-Dist: numpy
Provides-Extra: dev
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# cjm-ffmpeg-utils


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Install

``` bash
pip install cjm_ffmpeg_utils
```

``` bash
conda install conda-forge::ffmpeg
```

## Project Structure

    nbs/
    ├── audio.ipynb      # Audio extraction, conversion, and processing functions
    ├── core.ipynb       # Core utilities and exceptions for FFmpeg operations
    ├── execution.ipynb  # FFmpeg command execution with progress tracking
    ├── media_info.ipynb # Functions for getting media information and managing metadata
    └── video.ipynb      # Functions for generating test videos and audio files

Total: 5 notebooks

## Module Dependencies

``` mermaid
graph LR
    audio[audio<br/>Audio Processing]
    core[core<br/>Core]
    execution[execution<br/>Execution]
    media_info[media_info<br/>Media Info]
    video[video<br/>Video Generation]

    audio --> core
    audio --> execution
    audio --> media_info
    video --> core
```

*4 cross-module dependencies detected*

## CLI Reference

No CLI commands found in this project.

## Module Overview

Detailed documentation for each module in the project:

### Audio Processing (`audio.ipynb`)

> Audio extraction, conversion, and processing functions

#### Import

``` python
from cjm_ffmpeg_utils.audio import (
    extract_audio,
    downsample_audio,
    convert_to_mp3,
    extract_audio_segment
)
```

#### Functions

``` python
def extract_audio(input_path: Path, # Path to the input video file
                  output_path: Path, # Path for the output audio file
                  audio_format: str = 'mp3', # Output audio format (mp3, wav, flac, aac, etc.)
                  verbose: bool = False # If True, shows detailed ffmpeg output
                  )
    "Extract audio from a video file using ffmpeg."
```

``` python
def downsample_audio(input_path: Path, # Path to the input audio file
                    output_path: Path, # Path for the output file
                    verbose: bool = False # If True, shows detailed ffmpeg output
                    )
    "Downsample an audio file to 16kbps and single channel using ffmpeg."
```

``` python
def convert_to_mp3(input_path: Path, # Path to the input audio file
                   output_path: Path, # Path where the MP3 file will be saved
                   bitrate: str = "128k", # Audio bitrate for the output MP3 file
                   verbose: bool = False # Whether to display verbose output during conversion
                   ) -> Path: # Path to the converted MP3 file
    "Convert an audio file to MP3 format."
```

``` python
def extract_audio_segment(input_path: Path, # Path to the input audio file
                          output_path: Path, # Path where the extracted segment will be saved
                          start_time: str, # Start time in format "HH:MM:SS" or seconds
                          duration: str, # Duration in format "HH:MM:SS" or seconds
                          verbose: bool = False, # Whether to show verbose output
                          pbar: bool = False # Whether to show a progress bar
                        )
    "Extract a segment from an audio file."
```

### Core (`core.ipynb`)

> Core utilities and exceptions for FFmpeg operations

#### Import

``` python
from cjm_ffmpeg_utils.core import (
    FFMPEG_AVAILABLE,
    AudioProcessingError,
    AudioConversionError,
    get_audio_codec
)
```

#### Functions

``` python
def get_audio_codec(audio_format: str # The desired audio format
                   ) -> str: # The ffmpeg codec name
    "Get the appropriate audio codec for the given format."
```

#### Classes

``` python
class AudioProcessingError(Exception):
    "Base exception for audio processing errors"
```

``` python
class AudioConversionError(Exception):
    "Raised when audio format conversion fails"
```

#### Variables

``` python
FFMPEG_AVAILABLE
```

### Execution (`execution.ipynb`)

> FFmpeg command execution with progress tracking

#### Import

``` python
from cjm_ffmpeg_utils.execution import (
    parse_progress_line,
    run_ffmpeg_with_progress
)
```

#### Functions

``` python
def parse_progress_line(line: str # A line of stderr output from ffmpeg
                        ) -> Optional[float]: # Current time in seconds, or None if line doesn't contain progress info
    "Parse a progress line from ffmpeg stderr output."
```

``` python
def run_ffmpeg_with_progress(
    cmd: List[str], # List containing the ffmpeg command and arguments
    total_duration: Optional[float] = None, # Total duration in seconds for determinate progress, or None for indeterminate progress
    description: str = "Processing", # Description text for the progress bar
    verbose: bool = False, # If True, shows detailed ffmpeg output
    progress_callback: Optional[Callable[[float], None]] = None # Optional callback function that receives current progress in seconds as an argument
) -> None: # Raises FileNotFoundError if ffmpeg is not installed/found, or subprocess.CalledProcessError if ffmpeg command fails
    """
    Run an ffmpeg command with a progress bar.
    <br>
    Raises:<br>
    - FileNotFoundError: If input file doesn't exist<br>
    - subprocess.CalledProcessError: If ffmpeg command fails<br>
    - FileNotFoundError: If ffmpeg is not installed/found<br>
    """
```

### Media Info (`media_info.ipynb`)

> Functions for getting media information and managing metadata

#### Import

``` python
from cjm_ffmpeg_utils.media_info import (
    get_media_duration,
    get_audio_info_ffmpeg,
    add_metadata_with_ffmpeg
)
```

#### Functions

``` python
def get_media_duration(file_path: Path # Path to the media file
                      ) -> Optional[float]: # Duration in seconds, or None if duration cannot be determined
    "Get the duration of a media file using ffprobe."
```

``` python
def get_audio_info_ffmpeg(
    file_path: Path  # Path to audio file
)
    "Get basic audio file information including title if available"
```

``` python
def add_metadata_with_ffmpeg(
    input_file,    # Path to input audio file - TODO: Add type hint
    metadata    # Dictionary of metadata key-value pairs - TODO: Add type hint
)
    "Add metadata to audio file using FFmpeg"
```

### Video Generation (`video.ipynb`)

> Functions for generating test videos and audio files

#### Import

``` python
from cjm_ffmpeg_utils.video import (
    generate_video_with_binaural_audio,
    generate_test_audio_file
)
```

#### Functions

``` python
def generate_video_with_binaural_audio(filename, duration=60, video_pattern="mandelbrot", 
                                     wave_type="alpha", base_freq=200, resolution="1920x1080")
    "Generate test video with binaural beats audio"
```

``` python
def generate_test_audio_file(
    save_path: Path  # TODO: Add description
)
    "Generate a test audio file with binaural beats"
```
