Audio & Video Processing Guide¶

brew install ffmpeg

sudo apt update
sudo apt install ffmpeg

choco install ffmpeg

# From your File Organizer directory
pip install -e ".[audio]"

python -c "from faster_whisper import WhisperModel; print('✓ Audio transcription ready')"

from pathlib import Path
from file_organizer.services.audio.transcriber import AudioTranscriber, ModelSize, ComputeType

# Initialize transcriber
transcriber = AudioTranscriber(
    model_size=ModelSize.SMALL,
    compute_type=ComputeType.FLOAT16,  # Use INT8 for CPU
    device="cuda"  # or "cpu"
)

# Transcribe audio file
audio_file = Path("~/Downloads/podcast-episode.mp3")
result = transcriber.transcribe(audio_file)

# Access results
print(f"Language: {result.language} ({result.language_confidence:.2%})")
print(f"Duration: {result.duration:.1f} seconds")
print(f"Text: {result.text}")

# Access segments with timestamps
for segment in result.segments:
    print(f"[{segment.start:.2f}s - {segment.end:.2f}s] {segment.text}")

from file_organizer.services.audio.transcriber import (
    AudioTranscriber,
    TranscriptionOptions,
    ModelSize,
    ComputeType
)

# Configure advanced options
options = TranscriptionOptions(
    language="en",  # Force English (None for auto-detect)
    word_timestamps=True,  # Enable word-level timestamps
    beam_size=5,  # Beam search size (higher = slower, more accurate)
    best_of=5,  # Number of candidates (higher = slower, more accurate)
    temperature=0.0,  # Sampling temperature (0 = deterministic)
    vad_filter=True,  # Voice Activity Detection (removes silence)
    initial_prompt="This is a technical podcast about AI and machine learning."
)

transcriber = AudioTranscriber(
    model_size=ModelSize.MEDIUM,
    compute_type=ComputeType.INT8_FLOAT16
)

result = transcriber.transcribe("interview.wav", options=options)

# Word-level timestamps
for segment in result.segments:
    if segment.words:
        for word in segment.words:
            print(f"{word.word} [{word.start:.2f}s] (confidence: {word.probability:.2%})")

# Language is detected automatically
result = transcriber.transcribe("audio.mp3")
print(f"Detected: {result.language}")

options = TranscriptionOptions(language="es")  # Spanish
result = transcriber.transcribe_with_options("audio.mp3", options)

from file_organizer.core.types import AUDIO_EXTENSIONS

file_path = "my-file.mp3"
is_supported = any(file_path.endswith(ext) for ext in AUDIO_EXTENSIONS)
print(f"Supported: {is_supported}")

import torch

print(f"CUDA available: {torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"GPU: {torch.cuda.get_device_name(0)}")
    print(f"VRAM: {torch.cuda.get_device_properties(0).total_memory / 1e9:.1f} GB")

transcriber = AudioTranscriber(
    model_size=ModelSize.SMALL,
    compute_type=ComputeType.FLOAT16,  # GPU-optimized
    device="cuda",
    num_workers=4  # Parallel processing
)

transcriber = AudioTranscriber(
    model_size=ModelSize.TINY,  # Smaller model
    compute_type=ComputeType.INT8,  # Quantized precision
    device="cpu",
    num_workers=1  # Limit workers to avoid thrashing
)

from pathlib import Path

audio_files = list(Path("~/Podcasts").glob("*.mp3"))

for audio_file in audio_files:
    try:
        result = transcriber.transcribe(audio_file)

        # Save transcription
        output_file = audio_file.with_suffix(".txt")
        output_file.write_text(result.text)

        print(f"✓ {audio_file.name}: {result.language} ({len(result.text)} chars)")
    except Exception as e:
        print(f"✗ {audio_file.name}: {e}")

from file_organizer.services.audio.organizer import AudioOrganizer
from file_organizer.services.audio.classifier import AudioClassifier
from file_organizer.services.audio.metadata_extractor import AudioMetadataExtractor

# Extract metadata
metadata_extractor = AudioMetadataExtractor()
metadata = metadata_extractor.extract("podcast.mp3")

# Transcribe audio
transcriber = AudioTranscriber(model_size=ModelSize.SMALL)
transcription = transcriber.transcribe("podcast.mp3")

# Classify audio type
classifier = AudioClassifier()
classification = classifier.classify(
    metadata=metadata,
    transcription=transcription
)

print(f"Type: {classification.audio_type}")
print(f"Confidence: {classification.confidence:.2%}")
print(f"Reasoning: {classification.reasoning}")

# Organize with AudioOrganizer
organizer = AudioOrganizer()
plan = organizer.preview_organization(
    files=[(Path("podcast.mp3"), classification.audio_type, metadata)],
    base_path=Path("~/Audio").expanduser(),
)
print(f"Planned moves: {len(plan.planned_moves)}")

file-organizer tui

FileNotFoundError: FFmpeg not found

# Verify FFmpeg installation
ffmpeg -version

# If not installed, see "Installing FFmpeg" section above

RuntimeError: CUDA out of memory

# 1. Use smaller model
transcriber = AudioTranscriber(model_size=ModelSize.TINY)

# 2. Use quantized compute type
transcriber = AudioTranscriber(compute_type=ComputeType.INT8)

# 3. Switch to CPU
transcriber = AudioTranscriber(device="cpu")

audio:
  transcription:
    enabled: true
    model_size: small
    compute_type: float16
    device: cuda  # or cpu
    language: null  # null for auto-detect
    word_timestamps: false
    vad_filter: true
    beam_size: 5
    best_of: 5
    temperature: 0.0

brew install ffmpeg

sudo apt update
sudo apt install ffmpeg

choco install ffmpeg

# From your File Organizer directory
pip install -e ".[video]"

python -c "import cv2; import scenedetect; print('✓ Video analysis ready')"

from pathlib import Path
from file_organizer.services.video.scene_detector import SceneDetector, DetectionMethod

# Initialize detector
detector = SceneDetector(
    method=DetectionMethod.CONTENT,
    threshold=27.0,
    min_scene_length=1.0  # seconds
)

# Detect scenes in video
video_file = Path("~/Videos/movie.mp4")
result = detector.detect_scenes(video_file)

# Access results
print(f"Video: {result.video_path.name}")
print(f"Duration: {result.total_duration:.1f} seconds")
print(f"FPS: {result.fps:.2f}")
print(f"Detected {len(result.scenes)} scenes")

# Access individual scenes
for scene in result.scenes:
    print(f"Scene {scene.scene_number}: {scene.start_time:.2f}s - {scene.end_time:.2f}s "
          f"({scene.duration:.2f}s, {scene.frame_count} frames)")

from file_organizer.services.video.scene_detector import SceneDetector, DetectionMethod

# High-sensitivity detection for subtle transitions
detector = SceneDetector(
    method=DetectionMethod.ADAPTIVE,
    threshold=15.0,  # Lower = more sensitive
    min_scene_length=0.5  # Allow shorter scenes
)

result = detector.detect_scenes("interview.mp4")

# Override method/threshold per video
result = detector.detect_scenes(
    "action-movie.mp4",
    method=DetectionMethod.CONTENT,
    threshold=40.0  # Less sensitive for fast-paced content
)

from pathlib import Path
from file_organizer.services.video.scene_detector import SceneDetector

detector = SceneDetector()
result = detector.detect_scenes("video.mp4")

# Extract thumbnail for each scene
output_dir = Path("~/Videos/thumbnails")
SceneDetector.extract_scene_thumbnails(
    video_path="video.mp4",
    result=result,
    output_dir=output_dir,
    frame_offset=0.5  # Extract frame 0.5s into each scene
)

print(f"Saved {len(result.scenes)} thumbnails to {output_dir}")

from file_organizer.services.video.scene_detector import SceneDetector

detector = SceneDetector()
result = detector.detect_scenes("video.mp4")

# Save scene list as CSV
SceneDetector.save_scene_list(result, "scenes.csv")

# CSV format:
# Scene,Start Time,End Time,Duration,Start Frame,End Frame,Frame Count,Score
# 1,0.00,5.23,5.23,0,157,157,0.850
# 2,5.23,12.45,7.22,157,373,216,0.920

from pathlib import Path
from file_organizer.services.video.metadata_extractor import VideoMetadataExtractor

# Initialize extractor
extractor = VideoMetadataExtractor()

# Extract metadata
video_file = Path("~/Videos/movie.mp4")
metadata = extractor.extract(video_file)

# Access metadata
print(f"File: {metadata.file_path.name}")
print(f"Size: {metadata.file_size / 1024 / 1024:.1f} MB")
print(f"Format: {metadata.format}")
print(f"Duration: {metadata.duration:.1f} seconds")
print(f"Resolution: {metadata.width}x{metadata.height}")
print(f"FPS: {metadata.fps:.2f}")
print(f"Codec: {metadata.codec}")
print(f"Bitrate: {metadata.bitrate / 1000:.0f} kbps")

from file_organizer.services.video.metadata_extractor import resolution_label

# Classify resolution
label = resolution_label(1920, 1080)
print(label)  # "1080p"

label = resolution_label(3840, 2160)
print(label)  # "4k"

label = resolution_label(1280, 720)
print(label)  # "720p"

from pathlib import Path
from file_organizer.services.video.scene_detector import SceneDetector

detector = SceneDetector()
video_files = list(Path("~/Videos").glob("*.mp4"))

# Batch detect scenes
results = detector.detect_scenes_batch(video_files)

# Process results
for result in results:
    print(f"{result.video_path.name}: {len(result.scenes)} scenes")

    # Save scene list for each video
    output_csv = result.video_path.with_suffix(".scenes.csv")
    SceneDetector.save_scene_list(result, output_csv)

from file_organizer.core.types import VIDEO_EXTENSIONS

file_path = "my-video.mp4"
is_recognized = any(file_path.endswith(ext) for ext in VIDEO_EXTENSIONS)
print(f"Recognized: {is_recognized}")

from pathlib import Path
from file_organizer.services.video.organizer import VideoOrganizer
from file_organizer.services.video.scene_detector import SceneDetector
from file_organizer.services.video.metadata_extractor import VideoMetadataExtractor

# Extract metadata
metadata_extractor = VideoMetadataExtractor()
metadata = metadata_extractor.extract("video.mp4")

# Detect scenes
detector = SceneDetector()
scene_result = detector.detect_scenes("video.mp4")

# Organize based on video characteristics
if len(scene_result.scenes) > 50:
    category = "long-form"
elif scene_result.total_duration < 60:
    category = "short-clips"
else:
    category = "standard"

print(f"Category: {category}")
print(f"Scenes: {len(scene_result.scenes)}")
print(f"Duration: {scene_result.total_duration:.1f}s")

from file_organizer.services.video.organizer import is_screen_recording

# Detect screen recordings by filename
if is_screen_recording("Screen Recording 2025-01-15 at 3.45.22 PM.mp4"):
    print("macOS QuickTime screen recording detected")

if is_screen_recording("2025-01-15 14-05-32.mp4"):
    print("OBS Studio recording detected")

# Supports patterns from:
# - macOS QuickTime
# - Windows Snipping Tool
# - OBS Studio
# - Xbox Game Bar
# - Camtasia

ImportError: No module named 'cv2'

# Verify installation
python -c "import cv2; print(cv2.__version__)"

# If not installed
pip install opencv-python>=4.8.0

ImportError: No module named 'scenedetect'

pip install scenedetect[opencv]>=0.6.0

# Remove brew version if conflicts occur
brew uninstall opencv

# Use pip version only
pip install opencv-python

# Ubuntu/Debian
sudo apt install libgl1-mesa-glx libglib2.0-0

# Fedora/RHEL
sudo dnf install mesa-libGL glib2

# Use prebuilt binaries
pip install opencv-python

# Avoid building from source unless necessary

ValueError: Failed to open video: video.mp4

import cv2
cap = cv2.VideoCapture("video.mp4")
print(f"Opened: {cap.isOpened()}")
cap.release()

# Increase threshold (less sensitive)
detector = SceneDetector(threshold=40.0)

# Increase minimum scene length
detector = SceneDetector(min_scene_length=2.0)  # 2 seconds minimum

# Decrease threshold (more sensitive)
detector = SceneDetector(threshold=15.0)

# Try different detection method
detector = SceneDetector(method=DetectionMethod.ADAPTIVE)

# Use threshold method for speed
detector = SceneDetector(
    method=DetectionMethod.THRESHOLD,
    threshold=30.0
)

# Skip scene extraction, metadata only
from file_organizer.services.video.metadata_extractor import VideoMetadataExtractor
extractor = VideoMetadataExtractor()
metadata = extractor.extract("video.mp4")  # Much faster than scene detection

# Use adaptive method for accuracy
detector = SceneDetector(
    method=DetectionMethod.ADAPTIVE,
    min_scene_length=0.5  # Detect shorter scenes
)

# Extract high-resolution thumbnails
SceneDetector.extract_scene_thumbnails(
    video_path="video.mp4",
    result=result,
    output_dir="thumbnails",
    frame_offset=1.0  # Use frame 1s into scene
)

video:
  scene_detection:
    enabled: true
    method: content  # content, threshold, adaptive, histogram
    threshold: 27.0
    min_scene_length: 1.0
  metadata:
    use_ffprobe: true  # Prefer ffprobe over OpenCV
    extract_thumbnails: false
  organization:
    detect_screen_recordings: true
    short_clip_threshold: 60.0  # seconds

# Check Python version (requires 3.11+)
python3 --version

# Check FFmpeg installation
ffmpeg -version

# Check pip installation
pip --version

# Test faster-whisper installation
python -c "from faster_whisper import WhisperModel; print('✓ faster-whisper installed')"

# Test torch installation
python -c "import torch; print(f'✓ PyTorch {torch.__version__} installed')"

# Test audio metadata libraries
python -c "import mutagen; import tinytag; print('✓ Audio metadata libraries installed')"

# Check GPU availability (if applicable)
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"

✓ faster-whisper installed
✓ PyTorch 2.1.0+ installed
✓ Audio metadata libraries installed
CUDA available: True  # or False if no GPU

# Create test script
cat > test_audio.py << 'EOF'
from file_organizer.services.audio.transcriber import AudioTranscriber, ModelSize, ComputeType
from pathlib import Path
import sys

try:
    # Initialize with smallest model for quick test
    print("Initializing transcriber...")
    transcriber = AudioTranscriber(
        model_size=ModelSize.TINY,
        compute_type=ComputeType.INT8,
        device="cpu"
    )
    print("✓ Transcriber initialized successfully")

    # Test with a sample file if provided
    if len(sys.argv) > 1:
        audio_file = Path(sys.argv[1])
        if audio_file.exists():
            print(f"Transcribing {audio_file.name}...")
            result = transcriber.transcribe(audio_file)
            print(f"✓ Transcription completed")
            print(f"  Language: {result.language}")
            print(f"  Duration: {result.duration:.1f}s")
            print(f"  Text preview: {result.text[:100]}...")
        else:
            print(f"✗ File not found: {audio_file}")
            sys.exit(1)
    else:
        print("✓ Ready to transcribe (pass audio file path as argument)")

except Exception as e:
    print(f"✗ Error: {e}")
    sys.exit(1)
EOF

# Run test (without audio file)
python test_audio.py

# Or test with your own audio file
# python test_audio.py ~/path/to/your/audio.mp3

Initializing transcriber...
✓ Transcriber initialized successfully
✓ Ready to transcribe (pass audio file path as argument)

# Create metadata test script
cat > test_audio_metadata.py << 'EOF'
from file_organizer.services.audio.metadata_extractor import AudioMetadataExtractor
from pathlib import Path
import sys

if len(sys.argv) < 2:
    print("Usage: python test_audio_metadata.py <audio_file>")
    print("Note: Metadata extraction requires an actual audio file")
    sys.exit(0)

try:
    extractor = AudioMetadataExtractor()
    audio_file = Path(sys.argv[1])

    print(f"Extracting metadata from {audio_file.name}...")
    metadata = extractor.extract(audio_file)

    print("✓ Metadata extraction successful")
    print(f"  Title: {metadata.title or 'N/A'}")
    print(f"  Artist: {metadata.artist or 'N/A'}")
    print(f"  Duration: {metadata.duration:.1f}s")
    print(f"  Bitrate: {metadata.bitrate / 1000:.0f} kbps")
    print(f"  Format: {metadata.format}")

except Exception as e:
    print(f"✗ Error: {e}")
    sys.exit(1)
EOF

# This requires an actual audio file to test
echo "✓ Metadata test script created (run with: python test_audio_metadata.py <audio_file>)"

# Test OpenCV installation
python -c "import cv2; print(f'✓ OpenCV {cv2.__version__} installed')"

# Test PySceneDetect installation
python -c "import scenedetect; print(f'✓ PySceneDetect {scenedetect.__version__} installed')"

# Test video capture capability
python -c "import cv2; cap = cv2.VideoCapture(); print('✓ Video capture available')"

✓ OpenCV 4.8.0+ installed
✓ PySceneDetect 0.6.0+ installed
✓ Video capture available

# Create test script
cat > test_video.py << 'EOF'
from file_organizer.services.video.scene_detector import SceneDetector, DetectionMethod
from pathlib import Path
import sys

try:
    # Initialize detector
    print("Initializing scene detector...")
    detector = SceneDetector(
        method=DetectionMethod.CONTENT,
        threshold=27.0
    )
    print("✓ Scene detector initialized successfully")

    # Test with a sample file if provided
    if len(sys.argv) > 1:
        video_file = Path(sys.argv[1])
        if video_file.exists():
            print(f"Detecting scenes in {video_file.name}...")
            result = detector.detect_scenes(video_file)
            print(f"✓ Scene detection completed")
            print(f"  Duration: {result.total_duration:.1f}s")
            print(f"  FPS: {result.fps:.2f}")
            print(f"  Scenes detected: {len(result.scenes)}")
            if result.scenes:
                print(f"  First scene: {result.scenes[0].start_time:.2f}s - {result.scenes[0].end_time:.2f}s")
        else:
            print(f"✗ File not found: {video_file}")
            sys.exit(1)
    else:
        print("✓ Ready to detect scenes (pass video file path as argument)")

except Exception as e:
    print(f"✗ Error: {e}")
    sys.exit(1)
EOF

# Run test (without video file)
python test_video.py

# Or test with your own video file
# python test_video.py ~/path/to/your/video.mp4

Initializing scene detector...
✓ Scene detector initialized successfully
✓ Ready to detect scenes (pass video file path as argument)

# Create metadata test script
cat > test_video_metadata.py << 'EOF'
from file_organizer.services.video.metadata_extractor import VideoMetadataExtractor, resolution_label
from pathlib import Path
import sys

if len(sys.argv) < 2:
    print("Usage: python test_video_metadata.py <video_file>")
    print("Note: Metadata extraction requires an actual video file")
    sys.exit(0)

try:
    extractor = VideoMetadataExtractor()
    video_file = Path(sys.argv[1])

    print(f"Extracting metadata from {video_file.name}...")
    metadata = extractor.extract(video_file)

    print("✓ Metadata extraction successful")
    print(f"  Size: {metadata.file_size / 1024 / 1024:.1f} MB")
    print(f"  Format: {metadata.format}")
    print(f"  Duration: {metadata.duration:.1f}s")
    print(f"  Resolution: {metadata.width}x{metadata.height} ({resolution_label(metadata.width, metadata.height)})")
    print(f"  FPS: {metadata.fps:.2f}")
    print(f"  Codec: {metadata.codec}")
    print(f"  Bitrate: {metadata.bitrate / 1000:.0f} kbps")

except Exception as e:
    print(f"✗ Error: {e}")
    sys.exit(1)
EOF

# This requires an actual video file to test
echo "✓ Metadata test script created (run with: python test_video_metadata.py <video_file>)"

# Create integration test script
cat > test_integration.py << 'EOF'
import sys
from pathlib import Path

def test_audio_video_integration():
    """Test that audio and video processing can be imported together"""
    try:
        # Import audio components
        from file_organizer.services.audio.transcriber import AudioTranscriber
        from file_organizer.services.audio.metadata_extractor import AudioMetadataExtractor
        print("✓ Audio processing modules imported")

        # Import video components
        from file_organizer.services.video.scene_detector import SceneDetector
        from file_organizer.services.video.metadata_extractor import VideoMetadataExtractor
        print("✓ Video processing modules imported")

        # Test initialization
        audio_transcriber = AudioTranscriber()
        audio_metadata = AudioMetadataExtractor()
        video_detector = SceneDetector()
        video_metadata = VideoMetadataExtractor()
        print("✓ All processors initialized successfully")

        print("\n✓ Integration test PASSED")
        print("  Audio and video processing are ready to use")
        return True

    except Exception as e:
        print(f"\n✗ Integration test FAILED: {e}")
        return False

if __name__ == "__main__":
    success = test_audio_video_integration()
    sys.exit(0 if success else 1)
EOF

# Run integration test
python test_integration.py

✓ Audio processing modules imported
✓ Video processing modules imported
✓ All processors initialized successfully

✓ Integration test PASSED
  Audio and video processing are ready to use

# One-line verification
python -c "
import sys
try:
    from faster_whisper import WhisperModel
    import torch, cv2, scenedetect
    from file_organizer.services.audio.transcriber import AudioTranscriber
    from file_organizer.services.video.scene_detector import SceneDetector
    print('✓ All audio/video dependencies installed')
    print(f'  - PyTorch: {torch.__version__}')
    print(f'  - OpenCV: {cv2.__version__}')
    print(f'  - PySceneDetect: {scenedetect.__version__}')
    print(f'  - CUDA: {torch.cuda.is_available()}')
except ImportError as e:
    print(f'✗ Missing dependency: {e}')
    sys.exit(1)
"

✓ All audio/video dependencies installed
  - PyTorch: 2.1.0+
  - OpenCV: 4.8.0+
  - PySceneDetect: 0.6.0+
  - CUDA: True/False

rm -f test_audio.py test_audio_metadata.py test_video.py test_video_metadata.py test_integration.py