# 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 --> media_info
audio --> execution
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
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."
```
``` 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"
```
Raw data
{
"_id": null,
"home_page": "https://github.com/cj-mills/cjm-ffmpeg-utils",
"name": "cjm-ffmpeg-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "nbdev jupyter notebook python",
"author": "Christian J. Mills",
"author_email": "9126128+cj-mills@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/08/d0/72991a55ab411a504ec9227322820d689d03b2d12da7641cabbed90fbdff/cjm_ffmpeg_utils-0.0.3.tar.gz",
"platform": null,
"description": "# cjm-ffmpeg-utils\n\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\n## Install\n\n``` bash\npip install cjm_ffmpeg_utils\n```\n\n``` bash\nconda install conda-forge::ffmpeg\n```\n\n## Project Structure\n\n nbs/\n \u251c\u2500\u2500 audio.ipynb # Audio extraction, conversion, and processing functions\n \u251c\u2500\u2500 core.ipynb # Core utilities and exceptions for FFmpeg operations\n \u251c\u2500\u2500 execution.ipynb # FFmpeg command execution with progress tracking\n \u251c\u2500\u2500 media_info.ipynb # Functions for getting media information and managing metadata\n \u2514\u2500\u2500 video.ipynb # Functions for generating test videos and audio files\n\nTotal: 5 notebooks\n\n## Module Dependencies\n\n``` mermaid\ngraph LR\n audio[audio<br/>Audio Processing]\n core[core<br/>Core]\n execution[execution<br/>Execution]\n media_info[media_info<br/>Media Info]\n video[video<br/>Video Generation]\n\n audio --> core\n audio --> media_info\n audio --> execution\n video --> core\n```\n\n*4 cross-module dependencies detected*\n\n## CLI Reference\n\nNo CLI commands found in this project.\n\n## Module Overview\n\nDetailed documentation for each module in the project:\n\n### Audio Processing (`audio.ipynb`)\n\n> Audio extraction, conversion, and processing functions\n\n#### Import\n\n``` python\nfrom cjm_ffmpeg_utils.audio import (\n extract_audio,\n downsample_audio,\n convert_to_mp3,\n extract_audio_segment\n)\n```\n\n#### Functions\n\n``` python\ndef extract_audio(input_path: Path, # Path to the input video file\n output_path: Path, # Path for the output audio file\n audio_format: str = 'mp3', # Output audio format (mp3, wav, flac, aac, etc.)\n verbose: bool = False # If True, shows detailed ffmpeg output\n )\n \"Extract audio from a video file using ffmpeg.\"\n```\n\n``` python\ndef downsample_audio(input_path: Path, # Path to the input audio file\n output_path: Path, # Path for the output file\n sample_rate: Union[int, str] = \"16k\", # Audio bitrate\n channels: Union[int, str] = \"1\", # Audio channels\n overwrite: bool = True, # Overwrite existing output file\n verbose: bool = False # If True, shows detailed ffmpeg output\n )\n \"Downsample an audio file to 16kbps and single channel using ffmpeg.\"\n```\n\n``` python\ndef convert_to_mp3(input_path: Path, # Path to the input audio file\n output_path: Path, # Path where the MP3 file will be saved\n bitrate: str = \"128k\", # Audio bitrate for the output MP3 file\n verbose: bool = False # Whether to display verbose output during conversion\n ) -> Path: # Path to the converted MP3 file\n \"Convert an audio file to MP3 format.\"\n```\n\n``` python\ndef extract_audio_segment(input_path: Path, # Path to the input audio file\n output_path: Path, # Path where the extracted segment will be saved\n start_time: str, # Start time in format \"HH:MM:SS\" or seconds\n duration: str, # Duration in format \"HH:MM:SS\" or seconds\n verbose: bool = False, # Whether to show verbose output\n pbar: bool = False # Whether to show a progress bar\n )\n \"Extract a segment from an audio file.\"\n```\n\n### Core (`core.ipynb`)\n\n> Core utilities and exceptions for FFmpeg operations\n\n#### Import\n\n``` python\nfrom cjm_ffmpeg_utils.core import (\n FFMPEG_AVAILABLE,\n AudioProcessingError,\n AudioConversionError,\n get_audio_codec\n)\n```\n\n#### Functions\n\n``` python\ndef get_audio_codec(audio_format: str # The desired audio format\n ) -> str: # The ffmpeg codec name\n \"Get the appropriate audio codec for the given format.\"\n```\n\n#### Classes\n\n``` python\nclass AudioProcessingError(Exception):\n \"Base exception for audio processing errors\"\n```\n\n``` python\nclass AudioConversionError(Exception):\n \"Raised when audio format conversion fails\"\n```\n\n#### Variables\n\n``` python\nFFMPEG_AVAILABLE\n```\n\n### Execution (`execution.ipynb`)\n\n> FFmpeg command execution with progress tracking\n\n#### Import\n\n``` python\nfrom cjm_ffmpeg_utils.execution import (\n parse_progress_line,\n run_ffmpeg_with_progress\n)\n```\n\n#### Functions\n\n``` python\ndef parse_progress_line(line: str # A line of stderr output from ffmpeg\n ) -> Optional[float]: # Current time in seconds, or None if line doesn't contain progress info\n \"Parse a progress line from ffmpeg stderr output.\"\n```\n\n``` python\ndef run_ffmpeg_with_progress(\n cmd: List[str], # List containing the ffmpeg command and arguments\n total_duration: Optional[float] = None, # Total duration in seconds for determinate progress, or None for indeterminate progress\n description: str = \"Processing\", # Description text for the progress bar\n verbose: bool = False, # If True, shows detailed ffmpeg output\n progress_callback: Optional[Callable[[float], None]] = None # Optional callback function that receives current progress in seconds as an argument\n) -> None: # Raises FileNotFoundError if ffmpeg is not installed/found, or subprocess.CalledProcessError if ffmpeg command fails\n \"\"\"\n Run an ffmpeg command with a progress bar.\n <br>\n Raises:<br>\n - FileNotFoundError: If input file doesn't exist<br>\n - subprocess.CalledProcessError: If ffmpeg command fails<br>\n - FileNotFoundError: If ffmpeg is not installed/found<br>\n \"\"\"\n```\n\n### Media Info (`media_info.ipynb`)\n\n> Functions for getting media information and managing metadata\n\n#### Import\n\n``` python\nfrom cjm_ffmpeg_utils.media_info import (\n get_media_duration,\n get_audio_info_ffmpeg,\n add_metadata_with_ffmpeg\n)\n```\n\n#### Functions\n\n``` python\ndef get_media_duration(file_path: Path # Path to the media file\n ) -> Optional[float]: # Duration in seconds, or None if duration cannot be determined\n \"Get the duration of a media file using ffprobe.\"\n```\n\n``` python\ndef get_audio_info_ffmpeg(\n file_path: Path # Path to audio file\n)\n \"Get basic audio file information including title if available\"\n```\n\n``` python\ndef add_metadata_with_ffmpeg(\n input_file, # Path to input audio file - TODO: Add type hint\n metadata # Dictionary of metadata key-value pairs - TODO: Add type hint\n)\n \"Add metadata to audio file using FFmpeg\"\n```\n\n### Video Generation (`video.ipynb`)\n\n> Functions for generating test videos and audio files\n\n#### Import\n\n``` python\nfrom cjm_ffmpeg_utils.video import (\n generate_video_with_binaural_audio,\n generate_test_audio_file\n)\n```\n\n#### Functions\n\n``` python\ndef generate_video_with_binaural_audio(filename, duration=60, video_pattern=\"mandelbrot\", \n wave_type=\"alpha\", base_freq=200, resolution=\"1920x1080\")\n \"Generate test video with binaural beats audio\"\n```\n\n``` python\ndef generate_test_audio_file(\n save_path: Path # TODO: Add description\n)\n \"Generate a test audio file with binaural beats\"\n```\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Audio/video processing utilities with FFmpeg: extraction, conversion, metadata handling, and progress bars.",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/cj-mills/cjm-ffmpeg-utils"
},
"split_keywords": [
"nbdev",
"jupyter",
"notebook",
"python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4b8513372523aa37b19b599dd1957ae7562477c8e050ee34bb395605a3a4990b",
"md5": "2487af929ab1b5a45123354c373c7eac",
"sha256": "13af0072c466772741a1e11cf1f9c2502c06f3745dc700c443b43cf9fa15498f"
},
"downloads": -1,
"filename": "cjm_ffmpeg_utils-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2487af929ab1b5a45123354c373c7eac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 17467,
"upload_time": "2025-09-01T21:12:15",
"upload_time_iso_8601": "2025-09-01T21:12:15.301166Z",
"url": "https://files.pythonhosted.org/packages/4b/85/13372523aa37b19b599dd1957ae7562477c8e050ee34bb395605a3a4990b/cjm_ffmpeg_utils-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "08d072991a55ab411a504ec9227322820d689d03b2d12da7641cabbed90fbdff",
"md5": "a22d2bdbd44284239514bac7f9d56874",
"sha256": "d519cc75317c4c340449756430142d298631cfb01ca33372723ddd80dbaf61a9"
},
"downloads": -1,
"filename": "cjm_ffmpeg_utils-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "a22d2bdbd44284239514bac7f9d56874",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 16789,
"upload_time": "2025-09-01T21:12:16",
"upload_time_iso_8601": "2025-09-01T21:12:16.526433Z",
"url": "https://files.pythonhosted.org/packages/08/d0/72991a55ab411a504ec9227322820d689d03b2d12da7641cabbed90fbdff/cjm_ffmpeg_utils-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 21:12:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cj-mills",
"github_project": "cjm-ffmpeg-utils",
"github_not_found": true,
"lcname": "cjm-ffmpeg-utils"
}
JSON
