cjm-ffmpeg-utils

Install

pip install cjm_ffmpeg_utils

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

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

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

Functions

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."

def downsample_audio(input_path: Path, # Path to the input audio file
                     output_path: Path, # Path for the output file
                     sample_rate: Union[int, str] = "16k", # Audio bitrate
                     channels: Union[int, str] = "1", # Audio channels
                     overwrite: bool = True, # Overwrite existing output file
                     verbose: bool = False # If True, shows detailed ffmpeg output
                    )
    "Downsample an audio file to 16kbps and single channel using ffmpeg."

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."

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
                          copy_codec: bool = True, # Stream copy without re-encoding (fast)
                        ) -> None: # Raises subprocess.CalledProcessError if extraction fails
    "Extract a segment from an audio file."

Core (core.ipynb)

Core utilities and exceptions for FFmpeg operations

Import

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

Functions

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

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

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

Variables

FFMPEG_AVAILABLE

Execution (execution.ipynb)

FFmpeg command execution with progress tracking

Import

from cjm_ffmpeg_utils.execution import (
    parse_progress_line,
    run_ffmpeg_with_progress
)

Functions

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."

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 or subprocess.CalledProcessError if ffmpeg command fails
    "Run an ffmpeg command with a progress bar."

Media Info (media_info.ipynb)

Functions for getting media information and managing metadata

Import

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

Functions

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."

def get_audio_info_ffmpeg(
    file_path: Path  # Path to audio file
) -> Optional[Dict[str, any]]: # Dictionary containing audio info, or None if extraction fails
    "Get basic audio file information including title if available."

def add_metadata_with_ffmpeg(
    input_file: Path, # Path to input audio file
    metadata: Dict[str, str] # Dictionary of metadata key-value pairs
) -> bool: # True if metadata was added successfully, False otherwise
    "Add metadata to audio file using FFmpeg."

Video Generation (video.ipynb)

Functions for generating test videos and audio files

Import

from cjm_ffmpeg_utils.video import (
    generate_video_with_binaural_audio,
    generate_test_audio_file
)

Functions

def generate_video_with_binaural_audio(
    filename: str, # Output video filename
    duration: int = 60, # Video duration in seconds
    video_pattern: str = "mandelbrot", # FFmpeg video pattern (mandelbrot, life, etc.)
    wave_type: str = "alpha", # Brainwave type (delta, theta, alpha, beta, gamma)
    base_freq: int = 200, # Base frequency in Hz
    resolution: str = "1920x1080" # Video resolution
) -> bool: # True if video was generated successfully, False otherwise
    "Generate test video with binaural beats audio."

def generate_test_audio_file(
    save_path: Path # Path where the test audio file will be saved
) -> None: # No return value
    "Generate a test audio file with binaural beats."