cjm-ffmpeg-utils 0.0.2

Audio/video processing utilities with FFmpeg: extraction, conversion, metadata handling, and progress bars.

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

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
)
    "Get basic audio file information including title if available"

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

from cjm_ffmpeg_utils.video import (
    generate_video_with_binaural_audio,
    generate_test_audio_file
)

Functions

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"

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