Media Toolkit

display_name: 'Media Toolkit'
short_description: 'Handle practical audio and video conversion, trimming, and analysis.'
default_prompt: 'Help me process this audio or video file.'

#!/usr/bin/env python3
"""
Audio Analyzer - Comprehensive audio analysis toolkit.

Features:
- Tempo/BPM detection
- Key detection
- Frequency analysis
- Loudness metrics
- Waveform visualization
- Spectrogram generation
- Chromagram plotting
- Beat grid visualization
"""

import argparse
import json
import os
from pathlib import Path
from typing import Dict, List, Optional, Union, Any
from dataclasses import dataclass, asdict
import numpy as np


@dataclass
class TempoResult:
    """Tempo analysis results."""
    bpm: float
    confidence: float
    beats: List[float]
    beat_count: int


@dataclass
class KeyResult:
    """Key detection results."""
    key: str
    mode: str
    confidence: float
    profile: Dict[str, float]


@dataclass
class LoudnessResult:
    """Loudness analysis results."""
    rms_db: float
    peak_db: float
    lufs: float
    dynamic_range_db: float
    crest_factor: float


@dataclass
class FrequencyResult:
    """Frequency analysis results."""
    dominant_freq: float
    spectral_centroid: float
    spectral_rolloff: float
    bands: Dict[str, float]


class AudioAnalyzer:
    """Comprehensive audio analysis toolkit."""

    # Key names
    KEY_NAMES = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B']

    # Frequency bands (Hz)
    FREQ_BANDS = {
        'sub_bass': (20, 60),
        'bass': (60, 250),
        'low_mid': (250, 500),
        'mid': (500, 2000),
        'high_mid': (2000, 4000),
        'high': (4000, 20000)
    }

    def __init__(self, filepath: str, sr: int = 22050):
        """
        Initialize analyzer with audio file.

        Args:
            filepath: Path to audio file
            sr: Sample rate for analysis (default 22050)
        """
        self.filepath = Path(filepath)
        self.sr = sr
        self.y = None
        self.duration = 0.0

        # Results
        self._tempo: Optional[TempoResult] = None
        self._key: Optional[KeyResult] = None
        self._loudness: Optional[LoudnessResult] = None
        self._frequency: Optional[FrequencyResult] = None

        # Load audio
        self._load_audio()

    def _load_audio(self):
        """Load audio file using librosa."""
        try:
            import librosa
            self.y, self.sr = librosa.load(self.filepath, sr=self.sr, mono=True)
            self.duration = librosa.get_duration(y=self.y, sr=self.sr)
        except ImportError:
            raise ImportError("librosa is required. Install with: pip install librosa")
        except Exception as e:
            raise ValueError(f"Failed to load audio file: {e}")

    def analyze(self) -> 'AudioAnalyzer':
        """Run all analyses."""
        self.analyze_tempo()
        self.analyze_key()
        self.analyze_loudness()
        self.analyze_frequency()
        return self

    def analyze_tempo(self) -> 'AudioAnalyzer':
        """Detect tempo and beat positions."""
        import librosa

        # Get tempo and beat frames
        tempo, beat_frames = librosa.beat.beat_track(y=self.y, sr=self.sr)

        # Convert frames to time
        beat_times = librosa.frames_to_time(beat_frames, sr=self.sr)

        # Calculate confidence based on beat regularity
        if len(beat_times) > 1:
            intervals = np.diff(beat_times)
            expected_interval = 60.0 / float(tempo)
            interval_variance = np.var(intervals - expected_interval)
            confidence = max(0, min(1, 1 - interval_variance * 10))
        else:
            confidence = 0.0

        self._tempo = TempoResult(
            bpm=float(tempo),
            confidence=float(confidence),
            beats=beat_times.tolist(),
            beat_count=len(beat_times)
        )

        return self

    def analyze_key(self) -> 'AudioAnalyzer':
        """Detect musical key."""
        import librosa

        # Compute chromagram
        chroma = librosa.feature.chroma_cqt(y=self.y, sr=self.sr)

        # Average chroma over time
        chroma_avg = np.mean(chroma, axis=1)

        # Key profiles (Krumhansl-Schmuckler)
        major_profile = np.array([6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88])
        minor_profile = np.array([6.33, 2.68, 3.52, 5.38, 2.60, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17])

        # Correlate with all keys
        correlations = []
        for i in range(12):
            # Rotate profiles
            major_rot = np.roll(major_profile, i)
            minor_rot = np.roll(minor_profile, i)

            # Compute correlations
            corr_major = np.corrcoef(chroma_avg, major_rot)[0, 1]
            corr_minor = np.corrcoef(chroma_avg, minor_rot)[0, 1]

            correlations.append((i, 'major', corr_major))
            correlations.append((i, 'minor', corr_minor))

        # Find best match
        best = max(correlations, key=lambda x: x[2])
        key_idx, mode, confidence = best

        # Build profile dict
        profile = {self.KEY_NAMES[i]: float(chroma_avg[i]) for i in range(12)}

        self._key = KeyResult(
            key=self.KEY_NAMES[key_idx],
            mode=mode,
            confidence=float(max(0, confidence)),
            profile=profile
        )

        return self

    def analyze_loudness(self) -> 'AudioAnalyzer':
        """Analyze loudness metrics."""
        # RMS
        rms = np.sqrt(np.mean(self.y ** 2))
        rms_db = 20 * np.log10(rms + 1e-10)

        # Peak
        peak = np.max(np.abs(self.y))
        peak_db = 20 * np.log10(peak + 1e-10)

        # Simplified LUFS (approximation)
        # Real LUFS requires K-weighting filter
        lufs = rms_db - 0.691  # Rough approximation

        # Dynamic range (difference between 95th and 5th percentile)
        y_abs = np.abs(self.y)
        y_abs = y_abs[y_abs > 1e-10]  # Remove silence
        if len(y_abs) > 0:
            high = np.percentile(y_abs, 95)
            low = np.percentile(y_abs, 5)
            dynamic_range = 20 * np.log10(high / low + 1e-10)
        else:
            dynamic_range = 0.0

        # Crest factor
        crest_factor = peak / (rms + 1e-10)

        self._loudness = LoudnessResult(
            rms_db=float(rms_db),
            peak_db=float(peak_db),
            lufs=float(lufs),
            dynamic_range_db=float(dynamic_range),
            crest_factor=float(crest_factor)
        )

        return self

    def analyze_frequency(self) -> 'AudioAnalyzer':
        """Analyze frequency content."""
        import librosa

        # Compute spectrum
        D = np.abs(librosa.stft(self.y))
        freqs = librosa.fft_frequencies(sr=self.sr)

        # Average magnitude spectrum
        mag_avg = np.mean(D, axis=1)

        # Dominant frequency
        dominant_idx = np.argmax(mag_avg)
        dominant_freq = freqs[dominant_idx]

        # Spectral centroid
        centroid = librosa.feature.spectral_centroid(y=self.y, sr=self.sr)
        spectral_centroid = float(np.mean(centroid))

        # Spectral rolloff
        rolloff = librosa.feature.spectral_rolloff(y=self.y, sr=self.sr, roll_percent=0.85)
        spectral_rolloff = float(np.mean(rolloff))

        # Frequency band energy
        bands = {}
        for band_name, (low, high) in self.FREQ_BANDS.items():
            mask = (freqs >= low) & (freqs < high)
            if np.any(mask):
                band_energy = np.mean(mag_avg[mask])
                band_db = 20 * np.log10(band_energy + 1e-10)
            else:
                band_db = -60.0
            bands[band_name] = float(band_db)

        self._frequency = FrequencyResult(
            dominant_freq=float(dominant_freq),
            spectral_centroid=spectral_centroid,
            spectral_rolloff=spectral_rolloff,
            bands=bands
        )

        return self

    def get_tempo(self) -> Dict[str, Any]:
        """Get tempo analysis results."""
        if self._tempo is None:
            self.analyze_tempo()
        return asdict(self._tempo)

    def get_key(self) -> Dict[str, Any]:
        """Get key detection results."""
        if self._key is None:
            self.analyze_key()
        return asdict(self._key)

    def get_loudness(self) -> Dict[str, Any]:
        """Get loudness analysis results."""
        if self._loudness is None:
            self.analyze_loudness()
        return asdict(self._loudness)

    def get_frequency(self) -> Dict[str, Any]:
        """Get frequency analysis results."""
        if self._frequency is None:
            self.analyze_frequency()
        return asdict(self._frequency)

    def get_results(self) -> Dict[str, Any]:
        """Get all analysis results."""
        return {
            'file': str(self.filepath),
            'duration': self.duration,
            'sample_rate': self.sr,
            'tempo': self.get_tempo(),
            'key': self.get_key(),
            'loudness': self.get_loudness(),
            'frequency': self.get_frequency()
        }

    def get_summary(self) -> str:
        """Get human-readable summary."""
        results = self.get_results()

        lines = [
            f"Audio Analysis: {self.filepath.name}",
            f"Duration: {results['duration']:.1f} seconds",
            "",
            f"Tempo: {results['tempo']['bpm']:.1f} BPM (confidence: {results['tempo']['confidence']:.0%})",
            f"Key: {results['key']['key']} {results['key']['mode']} (confidence: {results['key']['confidence']:.0%})",
            "",
            "Loudness:",
            f"  RMS: {results['loudness']['rms_db']:.1f} dB",
            f"  Peak: {results['loudness']['peak_db']:.1f} dB",
            f"  LUFS: {results['loudness']['lufs']:.1f}",
            f"  Dynamic Range: {results['loudness']['dynamic_range_db']:.1f} dB",
            "",
            "Frequency:",
            f"  Dominant: {results['frequency']['dominant_freq']:.1f} Hz",
            f"  Centroid: {results['frequency']['spectral_centroid']:.1f} Hz",
            f"  Rolloff: {results['frequency']['spectral_rolloff']:.1f} Hz"
        ]

        return "\n".join(lines)

    def plot_waveform(
        self,
        output: str = "waveform.png",
        figsize: tuple = (12, 4),
        color: str = "#1f77b4",
        show_rms: bool = True
    ) -> str:
        """
        Plot waveform visualization.

        Args:
            output: Output file path
            figsize: Figure size (width, height)
            color: Waveform color
            show_rms: Show RMS envelope

        Returns:
            Path to saved file
        """
        import matplotlib.pyplot as plt
        import librosa.display

        fig, ax = plt.subplots(figsize=figsize)

        # Time axis
        times = np.linspace(0, self.duration, len(self.y))

        # Plot waveform
        ax.plot(times, self.y, color=color, alpha=0.7, linewidth=0.5)

        # RMS envelope
        if show_rms:
            import librosa
            rms = librosa.feature.rms(y=self.y)[0]
            rms_times = librosa.frames_to_time(np.arange(len(rms)), sr=self.sr)
            ax.plot(rms_times, rms, color='red', alpha=0.8, linewidth=1.5, label='RMS')
            ax.plot(rms_times, -rms, color='red', alpha=0.8, linewidth=1.5)

        ax.set_xlabel('Time (s)')
        ax.set_ylabel('Amplitude')
        ax.set_title(f'Waveform: {self.filepath.name}')
        ax.set_xlim(0, self.duration)
        ax.axhline(0, color='gray', linewidth=0.5)

        plt.tight_layout()
        plt.savefig(output, dpi=150, bbox_inches='tight')
        plt.close()

        return output

    def plot_spectrogram(
        self,
        output: str = "spectrogram.png",
        figsize: tuple = (12, 6),
        cmap: str = "magma",
        freq_scale: str = "log",
        max_freq: int = 8000
    ) -> str:
        """
        Plot spectrogram visualization.

        Args:
            output: Output file path
            figsize: Figure size
            cmap: Colormap (viridis, plasma, inferno, magma)
            freq_scale: Frequency scale (linear, log, mel)
            max_freq: Maximum frequency to display (Hz)

        Returns:
            Path to saved file
        """
        import matplotlib.pyplot as plt
        import librosa
        import librosa.display

        fig, ax = plt.subplots(figsize=figsize)

        if freq_scale == 'mel':
            # Mel spectrogram
            S = librosa.feature.melspectrogram(y=self.y, sr=self.sr, fmax=max_freq)
            S_db = librosa.power_to_db(S, ref=np.max)
            img = librosa.display.specshow(
                S_db, x_axis='time', y_axis='mel',
                sr=self.sr, fmax=max_freq, cmap=cmap, ax=ax
            )
        else:
            # Regular spectrogram
            D = librosa.amplitude_to_db(np.abs(librosa.stft(self.y)), ref=np.max)
            img = librosa.display.specshow(
                D, x_axis='time', y_axis=freq_scale,
                sr=self.sr, cmap=cmap, ax=ax
            )

        fig.colorbar(img, ax=ax, format='%+2.0f dB')
        ax.set_title(f'Spectrogram: {self.filepath.name}')

        plt.tight_layout()
        plt.savefig(output, dpi=150, bbox_inches='tight')
        plt.close()

        return output

    def plot_chromagram(
        self,
        output: str = "chromagram.png",
        figsize: tuple = (12, 4)
    ) -> str:
        """
        Plot chromagram (pitch class distribution over time).

        Args:
            output: Output file path
            figsize: Figure size

        Returns:
            Path to saved file
        """
        import matplotlib.pyplot as plt
        import librosa
        import librosa.display

        fig, ax = plt.subplots(figsize=figsize)

        chroma = librosa.feature.chroma_cqt(y=self.y, sr=self.sr)
        img = librosa.display.specshow(
            chroma, x_axis='time', y_axis='chroma',
            sr=self.sr, cmap='coolwarm', ax=ax
        )

        fig.colorbar(img, ax=ax)
        ax.set_title(f'Chromagram: {self.filepath.name}')

        plt.tight_layout()
        plt.savefig(output, dpi=150, bbox_inches='tight')
        plt.close()

        return output

    def plot_beats(
        self,
        output: str = "beats.png",
        figsize: tuple = (12, 4),
        show_strength: bool = True
    ) -> str:
        """
        Plot beat grid with onset strength.

        Args:
            output: Output file path
            figsize: Figure size
            show_strength: Show onset strength envelope

        Returns:
            Path to saved file
        """
        import matplotlib.pyplot as plt
        import librosa

        fig, ax = plt.subplots(figsize=figsize)

        # Ensure tempo is analyzed
        if self._tempo is None:
            self.analyze_tempo()

        times = np.linspace(0, self.duration, len(self.y))

        # Plot waveform lightly
        ax.plot(times, self.y, color='gray', alpha=0.3, linewidth=0.5)

        # Onset strength
        if show_strength:
            onset_env = librosa.onset.onset_strength(y=self.y, sr=self.sr)
            onset_times = librosa.frames_to_time(np.arange(len(onset_env)), sr=self.sr)
            # Normalize
            onset_env = onset_env / np.max(onset_env) * np.max(np.abs(self.y))
            ax.plot(onset_times, onset_env, color='blue', alpha=0.6, label='Onset strength')

        # Plot beat markers
        for beat_time in self._tempo.beats:
            ax.axvline(beat_time, color='red', alpha=0.7, linewidth=1)

        ax.set_xlabel('Time (s)')
        ax.set_ylabel('Amplitude')
        ax.set_title(f'Beat Grid ({self._tempo.bpm:.1f} BPM): {self.filepath.name}')
        ax.set_xlim(0, self.duration)

        plt.tight_layout()
        plt.savefig(output, dpi=150, bbox_inches='tight')
        plt.close()

        return output

    def plot_dashboard(
        self,
        output: str = "dashboard.png",
        figsize: tuple = (14, 10)
    ) -> str:
        """
        Plot comprehensive analysis dashboard.

        Args:
            output: Output file path
            figsize: Figure size

        Returns:
            Path to saved file
        """
        import matplotlib.pyplot as plt
        import librosa
        import librosa.display

        # Ensure all analyses are done
        self.analyze()

        fig = plt.figure(figsize=figsize)

        # Create grid
        gs = fig.add_gridspec(3, 2, hspace=0.3, wspace=0.3)

        # 1. Waveform (top, full width)
        ax1 = fig.add_subplot(gs[0, :])
        times = np.linspace(0, self.duration, len(self.y))
        ax1.plot(times, self.y, color='#1f77b4', alpha=0.7, linewidth=0.5)
        for beat_time in self._tempo.beats[:50]:  # Limit beats shown
            ax1.axvline(beat_time, color='red', alpha=0.3, linewidth=0.5)
        ax1.set_xlabel('Time (s)')
        ax1.set_ylabel('Amplitude')
        ax1.set_title(f'Waveform with Beats ({self._tempo.bpm:.1f} BPM)')
        ax1.set_xlim(0, self.duration)

        # 2. Spectrogram (middle left)
        ax2 = fig.add_subplot(gs[1, 0])
        D = librosa.amplitude_to_db(np.abs(librosa.stft(self.y)), ref=np.max)
        img = librosa.display.specshow(D, x_axis='time', y_axis='log', sr=self.sr, cmap='magma', ax=ax2)
        fig.colorbar(img, ax=ax2, format='%+2.0f dB')
        ax2.set_title('Spectrogram')

        # 3. Chromagram (middle right)
        ax3 = fig.add_subplot(gs[1, 1])
        chroma = librosa.feature.chroma_cqt(y=self.y, sr=self.sr)
        img2 = librosa.display.specshow(chroma, x_axis='time', y_axis='chroma', sr=self.sr, cmap='coolwarm', ax=ax3)
        fig.colorbar(img2, ax=ax3)
        ax3.set_title(f'Chromagram (Key: {self._key.key} {self._key.mode})')

        # 4. Frequency bands (bottom left)
        ax4 = fig.add_subplot(gs[2, 0])
        bands = list(self._frequency.bands.keys())
        values = list(self._frequency.bands.values())
        colors = plt.cm.viridis(np.linspace(0.2, 0.8, len(bands)))
        ax4.barh(bands, values, color=colors)
        ax4.set_xlabel('Energy (dB)')
        ax4.set_title('Frequency Bands')
        ax4.axvline(0, color='gray', linewidth=0.5)

        # 5. Info panel (bottom right)
        ax5 = fig.add_subplot(gs[2, 1])
        ax5.axis('off')

        info_text = f"""
FILE: {self.filepath.name}
Duration: {self.duration:.1f}s

TEMPO
BPM: {self._tempo.bpm:.1f}
Confidence: {self._tempo.confidence:.0%}
Beats: {self._tempo.beat_count}

KEY
Key: {self._key.key} {self._key.mode}
Confidence: {self._key.confidence:.0%}

LOUDNESS
RMS: {self._loudness.rms_db:.1f} dB
Peak: {self._loudness.peak_db:.1f} dB
LUFS: {self._loudness.lufs:.1f}
Dynamic Range: {self._loudness.dynamic_range_db:.1f} dB

FREQUENCY
Dominant: {self._frequency.dominant_freq:.0f} Hz
Centroid: {self._frequency.spectral_centroid:.0f} Hz
"""
        ax5.text(0.1, 0.95, info_text, transform=ax5.transAxes,
                 fontsize=10, verticalalignment='top', fontfamily='monospace',
                 bbox=dict(boxstyle='round', facecolor='wheat', alpha=0.5))

        plt.suptitle(f'Audio Analysis Dashboard', fontsize=14, fontweight='bold')
        plt.savefig(output, dpi=150, bbox_inches='tight')
        plt.close()

        return output

    def save_report(self, path: str) -> str:
        """
        Save analysis report to JSON.

        Args:
            path: Output file path

        Returns:
            Path to saved file
        """
        results = self.get_results()

        with open(path, 'w') as f:
            json.dump(results, f, indent=2)

        return path


def main():
    """CLI entry point."""
    parser = argparse.ArgumentParser(
        description='Comprehensive audio analysis toolkit',
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  %(prog)s --input song.mp3 --output-dir ./analysis/
  %(prog)s --input song.mp3 --analyze tempo key --output report.json
  %(prog)s --input song.mp3 --plot spectrogram --output spec.png
  %(prog)s --input song.mp3 --dashboard --output dashboard.png
        """
    )

    parser.add_argument('--input', '-i', required=True, help='Input audio file')
    parser.add_argument('--input-dir', help='Directory of audio files for batch processing')
    parser.add_argument('--output', '-o', help='Output file path')
    parser.add_argument('--output-dir', default='.', help='Output directory (default: current)')
    parser.add_argument('--analyze', nargs='+',
                        choices=['tempo', 'key', 'loudness', 'frequency', 'all'],
                        default=['all'], help='Analysis types to run')
    parser.add_argument('--plot', choices=['waveform', 'spectrogram', 'chromagram', 'beats', 'dashboard'],
                        help='Generate specific plot')
    parser.add_argument('--dashboard', action='store_true', help='Generate full dashboard')
    parser.add_argument('--format', choices=['json', 'txt'], default='json', help='Output format')
    parser.add_argument('--sr', type=int, default=22050, help='Sample rate for analysis')

    args = parser.parse_args()

    # Create output directory
    os.makedirs(args.output_dir, exist_ok=True)

    # Process files
    if args.input_dir:
        # Batch mode
        audio_extensions = {'.mp3', '.wav', '.flac', '.ogg', '.m4a', '.aiff'}
        files = [f for f in Path(args.input_dir).iterdir()
                 if f.suffix.lower() in audio_extensions]
    else:
        files = [Path(args.input)]

    for filepath in files:
        print(f"Analyzing: {filepath.name}")

        try:
            analyzer = AudioAnalyzer(str(filepath), sr=args.sr)

            # Run analyses
            if 'all' in args.analyze:
                analyzer.analyze()
            else:
                if 'tempo' in args.analyze:
                    analyzer.analyze_tempo()
                if 'key' in args.analyze:
                    analyzer.analyze_key()
                if 'loudness' in args.analyze:
                    analyzer.analyze_loudness()
                if 'frequency' in args.analyze:
                    analyzer.analyze_frequency()

            # Generate outputs
            base_name = filepath.stem

            if args.dashboard or args.plot == 'dashboard':
                out_path = args.output or os.path.join(args.output_dir, f"{base_name}_dashboard.png")
                analyzer.plot_dashboard(out_path)
                print(f"  Dashboard: {out_path}")

            elif args.plot:
                out_path = args.output or os.path.join(args.output_dir, f"{base_name}_{args.plot}.png")
                if args.plot == 'waveform':
                    analyzer.plot_waveform(out_path)
                elif args.plot == 'spectrogram':
                    analyzer.plot_spectrogram(out_path)
                elif args.plot == 'chromagram':
                    analyzer.plot_chromagram(out_path)
                elif args.plot == 'beats':
                    analyzer.plot_beats(out_path)
                print(f"  Plot: {out_path}")

            else:
                # Output report
                if args.format == 'json':
                    out_path = args.output or os.path.join(args.output_dir, f"{base_name}_analysis.json")
                    analyzer.save_report(out_path)
                    print(f"  Report: {out_path}")
                else:
                    summary = analyzer.get_summary()
                    if args.output:
                        with open(args.output, 'w') as f:
                            f.write(summary)
                        print(f"  Summary: {args.output}")
                    else:
                        print(summary)

        except Exception as e:
            print(f"  Error: {e}")

    print("Done!")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Audio Converter - Convert audio files between formats.

Features:
- Format conversion (MP3, WAV, FLAC, OGG, M4A, AIFF)
- Bitrate and sample rate control
- Batch processing
- Volume normalization
"""

import argparse
import os
from pathlib import Path
from typing import Optional, List


class AudioConverter:
    """Convert audio files between formats."""

    SUPPORTED_FORMATS = {
        'mp3': {'codec': 'mp3', 'lossy': True},
        'wav': {'codec': 'pcm_s16le', 'lossy': False},
        'flac': {'codec': 'flac', 'lossy': False},
        'ogg': {'codec': 'libvorbis', 'lossy': True},
        'm4a': {'codec': 'aac', 'lossy': True},
        'aiff': {'codec': 'pcm_s16be', 'lossy': False}
    }

    def __init__(self, filepath: str):
        """
        Initialize converter with audio file.

        Args:
            filepath: Path to input audio file
        """
        self.filepath = Path(filepath)
        if not self.filepath.exists():
            raise FileNotFoundError(f"Audio file not found: {filepath}")

        self._bitrate: Optional[int] = None
        self._sample_rate: Optional[int] = None
        self._channels: Optional[int] = None
        self._normalize: bool = False

        # Load audio
        self._audio = None
        self._load_audio()

    def _load_audio(self):
        """Load audio file using pydub."""
        try:
            from pydub import AudioSegment
            self._audio = AudioSegment.from_file(str(self.filepath))
        except ImportError:
            raise ImportError("pydub is required. Install with: pip install pydub")
        except Exception as e:
            raise ValueError(f"Failed to load audio file: {e}")

    def bitrate(self, kbps: int) -> 'AudioConverter':
        """
        Set output bitrate for lossy formats.

        Args:
            kbps: Bitrate in kilobits per second (e.g., 128, 192, 320)

        Returns:
            Self for chaining
        """
        self._bitrate = kbps
        return self

    def sample_rate(self, hz: int) -> 'AudioConverter':
        """
        Set output sample rate.

        Args:
            hz: Sample rate in Hz (e.g., 44100, 48000)

        Returns:
            Self for chaining
        """
        self._sample_rate = hz
        return self

    def channels(self, num: int) -> 'AudioConverter':
        """
        Set number of output channels.

        Args:
            num: Number of channels (1=mono, 2=stereo)

        Returns:
            Self for chaining
        """
        self._channels = num
        return self

    def normalize(self, enable: bool = True) -> 'AudioConverter':
        """
        Enable/disable volume normalization.

        Args:
            enable: Whether to normalize

        Returns:
            Self for chaining
        """
        self._normalize = enable
        return self

    def convert(self, output: str, format: Optional[str] = None) -> str:
        """
        Convert audio to specified format.

        Args:
            output: Output file path
            format: Output format (optional, inferred from extension)

        Returns:
            Path to converted file
        """
        from pydub import AudioSegment

        output_path = Path(output)

        # Determine format
        if format is None:
            format = output_path.suffix.lstrip('.').lower()

        if format not in self.SUPPORTED_FORMATS:
            raise ValueError(f"Unsupported format: {format}. Supported: {list(self.SUPPORTED_FORMATS.keys())}")

        # Prepare audio
        audio = self._audio

        # Apply sample rate
        if self._sample_rate:
            audio = audio.set_frame_rate(self._sample_rate)

        # Apply channels
        if self._channels:
            if self._channels == 1:
                audio = audio.set_channels(1)
            elif self._channels == 2:
                audio = audio.set_channels(2)

        # Normalize
        if self._normalize:
            # Normalize to -3 dB
            change_in_dBFS = -3 - audio.dBFS
            audio = audio.apply_gain(change_in_dBFS)

        # Ensure output directory exists
        output_path.parent.mkdir(parents=True, exist_ok=True)

        # Build export parameters
        export_params = {}

        if self.SUPPORTED_FORMATS[format]['lossy']:
            # Lossy format - set bitrate
            bitrate = self._bitrate or 192
            export_params['bitrate'] = f"{bitrate}k"

        # Export
        audio.export(
            str(output_path),
            format=format,
            **export_params
        )

        return str(output_path)

    def get_info(self) -> dict:
        """
        Get information about the input audio.

        Returns:
            Dict with audio properties
        """
        return {
            'file': str(self.filepath),
            'format': self.filepath.suffix.lstrip('.'),
            'duration_ms': len(self._audio),
            'duration_sec': len(self._audio) / 1000,
            'channels': self._audio.channels,
            'sample_rate': self._audio.frame_rate,
            'sample_width': self._audio.sample_width,
            'frame_count': self._audio.frame_count(),
            'dBFS': self._audio.dBFS
        }

    @classmethod
    def batch_convert(
        cls,
        input_dir: str,
        output_dir: str,
        format: str,
        bitrate: Optional[int] = None,
        sample_rate: Optional[int] = None,
        channels: Optional[int] = None,
        normalize: bool = False
    ) -> List[str]:
        """
        Batch convert all audio files in a directory.

        Args:
            input_dir: Input directory path
            output_dir: Output directory path
            format: Output format
            bitrate: Bitrate in kbps (for lossy formats)
            sample_rate: Sample rate in Hz
            channels: Number of channels
            normalize: Whether to normalize volume

        Returns:
            List of converted file paths
        """
        input_path = Path(input_dir)
        output_path = Path(output_dir)

        if not input_path.exists():
            raise FileNotFoundError(f"Input directory not found: {input_dir}")

        output_path.mkdir(parents=True, exist_ok=True)

        # Find audio files
        audio_extensions = {'.mp3', '.wav', '.flac', '.ogg', '.m4a', '.aiff', '.aac', '.wma'}
        files = [f for f in input_path.iterdir() if f.suffix.lower() in audio_extensions]

        converted = []
        for filepath in files:
            try:
                converter = cls(str(filepath))

                if bitrate:
                    converter.bitrate(bitrate)
                if sample_rate:
                    converter.sample_rate(sample_rate)
                if channels:
                    converter.channels(channels)
                if normalize:
                    converter.normalize(True)

                output_file = output_path / f"{filepath.stem}.{format}"
                converter.convert(str(output_file), format=format)
                converted.append(str(output_file))
                print(f"Converted: {filepath.name} -> {output_file.name}")

            except Exception as e:
                print(f"Failed to convert {filepath.name}: {e}")

        return converted


def main():
    """CLI entry point."""
    parser = argparse.ArgumentParser(
        description='Convert audio files between formats',
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  %(prog)s --input song.wav --output song.mp3
  %(prog)s --input song.flac --output song.mp3 --bitrate 320
  %(prog)s --input-dir ./wavs --output-dir ./mp3s --format mp3 --bitrate 192
        """
    )

    parser.add_argument('--input', '-i', help='Input audio file')
    parser.add_argument('--output', '-o', help='Output file path')
    parser.add_argument('--input-dir', help='Input directory for batch processing')
    parser.add_argument('--output-dir', help='Output directory for batch processing')
    parser.add_argument('--format', '-f', help='Output format')
    parser.add_argument('--bitrate', '-b', type=int, help='Bitrate in kbps (for lossy formats)')
    parser.add_argument('--sample-rate', '-s', type=int, help='Sample rate in Hz')
    parser.add_argument('--channels', '-c', type=int, choices=[1, 2], help='Number of channels')
    parser.add_argument('--normalize', '-n', action='store_true', help='Normalize volume')
    parser.add_argument('--info', action='store_true', help='Show info about input file')

    args = parser.parse_args()

    # Validate arguments
    if args.input_dir:
        # Batch mode
        if not args.output_dir:
            parser.error("--output-dir is required for batch processing")
        if not args.format:
            parser.error("--format is required for batch processing")

        converted = AudioConverter.batch_convert(
            input_dir=args.input_dir,
            output_dir=args.output_dir,
            format=args.format,
            bitrate=args.bitrate,
            sample_rate=args.sample_rate,
            channels=args.channels,
            normalize=args.normalize
        )
        print(f"\nConverted {len(converted)} files")

    elif args.input:
        # Single file mode
        converter = AudioConverter(args.input)

        if args.info:
            info = converter.get_info()
            print(f"File: {info['file']}")
            print(f"Format: {info['format']}")
            print(f"Duration: {info['duration_sec']:.2f} seconds")
            print(f"Channels: {info['channels']}")
            print(f"Sample Rate: {info['sample_rate']} Hz")
            print(f"Level: {info['dBFS']:.1f} dBFS")
            return

        if not args.output:
            parser.error("--output is required for conversion")

        if args.bitrate:
            converter.bitrate(args.bitrate)
        if args.sample_rate:
            converter.sample_rate(args.sample_rate)
        if args.channels:
            converter.channels(args.channels)
        if args.normalize:
            converter.normalize(True)

        output = converter.convert(args.output, format=args.format)
        print(f"Converted: {args.input} -> {output}")

    else:
        parser.error("Either --input or --input-dir is required")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Audio Normalizer - Normalize audio volume using peak or RMS methods.

Features:
- Peak normalization to target dBFS
- RMS normalization for average loudness
- Loudness analysis
- Batch processing
- Format preservation
"""

import argparse
import os
import sys
from pathlib import Path
from typing import Dict, List, Optional
import numpy as np
from pydub import AudioSegment
from pydub.utils import db_to_float, ratio_to_db


class AudioNormalizer:
    """Normalize audio volume levels."""

    def __init__(self):
        self.audio = None
        self.filepath = None
        self.sample_rate = None

    def load(self, filepath: str) -> 'AudioNormalizer':
        """
        Load audio file.

        Args:
            filepath: Path to audio file

        Returns:
            Self for method chaining
        """
        if not os.path.exists(filepath):
            raise FileNotFoundError(f"Audio file not found: {filepath}")

        self.filepath = filepath
        # Auto-detect format from extension
        ext = Path(filepath).suffix[1:].lower()
        self.audio = AudioSegment.from_file(filepath, format=ext)
        self.sample_rate = self.audio.frame_rate

        return self

    def analyze_levels(self) -> Dict[str, float]:
        """
        Analyze current audio levels.

        Returns:
            Dictionary with peak and RMS levels in dBFS
        """
        if self.audio is None:
            raise ValueError("No audio loaded. Call load() first.")

        # Peak level (max dBFS)
        peak_dbfs = self.audio.max_dBFS

        # RMS level (average loudness)
        rms_dbfs = self.audio.dBFS

        # Crest factor (peak to RMS ratio)
        crest_factor = peak_dbfs - rms_dbfs

        return {
            'peak_dbfs': round(peak_dbfs, 2),
            'rms_dbfs': round(rms_dbfs, 2),
            'crest_factor': round(crest_factor, 2),
            'duration_seconds': len(self.audio) / 1000.0,
            'sample_rate': self.sample_rate,
            'channels': self.audio.channels
        }

    def normalize_peak(self, target_dbfs: float = -1.0, headroom: float = 0.1) -> 'AudioNormalizer':
        """
        Normalize audio to target peak level.

        Args:
            target_dbfs: Target peak level in dBFS (default: -1.0)
            headroom: Safety headroom in dB to prevent clipping (default: 0.1)

        Returns:
            Self for method chaining
        """
        if self.audio is None:
            raise ValueError("No audio loaded. Call load() first.")

        # Calculate current peak
        current_peak = self.audio.max_dBFS

        # Calculate gain needed (with headroom)
        gain_needed = (target_dbfs - headroom) - current_peak

        # Apply gain
        self.audio = self.audio.apply_gain(gain_needed)

        return self

    def normalize_rms(self, target_dbfs: float = -20.0) -> 'AudioNormalizer':
        """
        Normalize audio to target RMS (average loudness) level.

        Args:
            target_dbfs: Target RMS level in dBFS (default: -20.0)

        Returns:
            Self for method chaining
        """
        if self.audio is None:
            raise ValueError("No audio loaded. Call load() first.")

        # Calculate current RMS
        current_rms = self.audio.dBFS

        # Calculate gain needed
        gain_needed = target_dbfs - current_rms

        # Apply gain
        self.audio = self.audio.apply_gain(gain_needed)

        # Check for clipping after normalization
        if self.audio.max_dBFS > -0.1:
            print(f"Warning: Audio may clip (peak at {self.audio.max_dBFS:.2f} dBFS). "
                  f"Consider using peak normalization or lower target.")

        return self

    def match_loudness(self, reference_audio: 'AudioSegment') -> 'AudioNormalizer':
        """
        Match loudness to reference audio.

        Args:
            reference_audio: AudioSegment to match loudness to

        Returns:
            Self for method chaining
        """
        if self.audio is None:
            raise ValueError("No audio loaded. Call load() first.")

        # Get reference RMS
        reference_rms = reference_audio.dBFS

        # Normalize to match
        return self.normalize_rms(target_dbfs=reference_rms)

    def save(self, output: str, format: str = None, bitrate: str = '192k') -> str:
        """
        Save normalized audio.

        Args:
            output: Output filepath
            format: Output format (auto-detected from extension if None)
            bitrate: Output bitrate for compressed formats

        Returns:
            Path to saved file
        """
        if self.audio is None:
            raise ValueError("No audio loaded. Call load() first.")

        # Auto-detect format from extension
        if format is None:
            format = Path(output).suffix[1:].lower()

        # Create output directory if needed
        os.makedirs(os.path.dirname(output) or '.', exist_ok=True)

        # Export with parameters
        if format in ['mp3', 'ogg', 'm4a']:
            self.audio.export(output, format=format, bitrate=bitrate)
        else:
            self.audio.export(output, format=format)

        return output

    def batch_normalize(self, input_files: List[str], output_dir: str,
                       method: str = 'rms', target_dbfs: float = -20.0,
                       format: str = None) -> List[str]:
        """
        Normalize multiple audio files to same level.

        Args:
            input_files: List of input file paths
            output_dir: Output directory for normalized files
            method: Normalization method ('peak' or 'rms')
            target_dbfs: Target level in dBFS
            format: Output format (preserves input format if None)

        Returns:
            List of output file paths
        """
        os.makedirs(output_dir, exist_ok=True)
        output_files = []

        for i, input_file in enumerate(input_files, 1):
            print(f"Processing {i}/{len(input_files)}: {os.path.basename(input_file)}")

            # Load and analyze
            self.load(input_file)
            levels = self.analyze_levels()
            print(f"  Current: Peak={levels['peak_dbfs']:.2f} dB, RMS={levels['rms_dbfs']:.2f} dB")

            # Normalize
            if method == 'peak':
                self.normalize_peak(target_dbfs=target_dbfs)
            elif method == 'rms':
                self.normalize_rms(target_dbfs=target_dbfs)
            else:
                raise ValueError(f"Unknown method: {method}")

            # Save
            output_format = format or Path(input_file).suffix[1:]
            output_filename = Path(input_file).stem + f'_normalized.{output_format}'
            output_path = os.path.join(output_dir, output_filename)
            self.save(output_path, format=output_format)

            # Verify
            self.load(output_path)
            new_levels = self.analyze_levels()
            print(f"  Normalized: Peak={new_levels['peak_dbfs']:.2f} dB, RMS={new_levels['rms_dbfs']:.2f} dB")

            output_files.append(output_path)

        return output_files


def main():
    parser = argparse.ArgumentParser(
        description='Normalize audio volume levels',
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  # Peak normalization to -1 dBFS
  python audio_normalizer.py input.mp3 --output normalized.mp3 --method peak --target -1.0

  # RMS normalization for podcasts
  python audio_normalizer.py input.mp3 --output normalized.mp3 --method rms --target -19.0

  # Analyze current levels
  python audio_normalizer.py input.mp3 --analyze-only

  # Batch normalize all MP3s
  python audio_normalizer.py *.mp3 --output-dir normalized/ --method rms --target -20.0
        """
    )

    parser.add_argument('input', nargs='+', help='Input audio file(s)')
    parser.add_argument('--output', '-o', help='Output file (single file mode)')
    parser.add_argument('--output-dir', '-d', help='Output directory (batch mode)')
    parser.add_argument('--method', '-m', choices=['peak', 'rms'], default='rms',
                       help='Normalization method (default: rms)')
    parser.add_argument('--target', '-t', type=float, default=-20.0,
                       help='Target level in dBFS (default: -20.0 for RMS, -1.0 for peak)')
    parser.add_argument('--format', '-f', help='Output format (auto-detected from extension)')
    parser.add_argument('--bitrate', '-b', default='192k', help='Bitrate for compressed formats (default: 192k)')
    parser.add_argument('--analyze-only', '-a', action='store_true',
                       help='Analyze levels without normalizing')

    args = parser.parse_args()

    normalizer = AudioNormalizer()

    # Single file mode
    if len(args.input) == 1 and not args.output_dir:
        input_file = args.input[0]

        # Load and analyze
        normalizer.load(input_file)
        levels = normalizer.analyze_levels()

        print(f"\nAudio Analysis: {os.path.basename(input_file)}")
        print(f"  Peak Level: {levels['peak_dbfs']:.2f} dBFS")
        print(f"  RMS Level: {levels['rms_dbfs']:.2f} dBFS")
        print(f"  Crest Factor: {levels['crest_factor']:.2f} dB")
        print(f"  Duration: {levels['duration_seconds']:.2f} seconds")
        print(f"  Sample Rate: {levels['sample_rate']} Hz")
        print(f"  Channels: {levels['channels']}")

        if args.analyze_only:
            return

        if not args.output:
            print("\nError: --output required for single file normalization")
            return

        # Normalize
        if args.method == 'peak':
            target = args.target if args.target != -20.0 else -1.0
            normalizer.normalize_peak(target_dbfs=target)
        else:
            normalizer.normalize_rms(target_dbfs=args.target)

        # Save
        normalizer.save(args.output, format=args.format, bitrate=args.bitrate)

        # Verify
        normalizer.load(args.output)
        new_levels = normalizer.analyze_levels()
        print(f"\nNormalized Audio:")
        print(f"  Peak Level: {new_levels['peak_dbfs']:.2f} dBFS")
        print(f"  RMS Level: {new_levels['rms_dbfs']:.2f} dBFS")
        print(f"\nSaved: {args.output}")

    # Batch mode
    else:
        if not args.output_dir:
            print("Error: --output-dir required for batch processing")
            return

        target = args.target
        if args.method == 'peak' and target == -20.0:
            target = -1.0

        print(f"\nBatch normalizing {len(args.input)} files...")
        print(f"Method: {args.method.upper()} to {target:.1f} dBFS")
        print(f"Output directory: {args.output_dir}\n")

        output_files = normalizer.batch_normalize(
            input_files=args.input,
            output_dir=args.output_dir,
            method=args.method,
            target_dbfs=target,
            format=args.format
        )

        print(f"\n✓ Normalized {len(output_files)} files to {args.output_dir}")


if __name__ == '__main__':
    main()

#!/usr/bin/env python3
"""
Audio Trimmer - Cut, trim, and edit audio segments.

Features:
- Precise trimming by timestamp
- Fade in/out effects
- Speed control
- Concatenation with crossfade
- Basic audio effects
- Volume adjustment
"""

import argparse
import re
from pathlib import Path
from typing import List, Optional, Tuple, Union


class AudioTrimmer:
    """Cut, trim, and edit audio segments."""

    def __init__(self, filepath: str):
        """
        Initialize trimmer with audio file.

        Args:
            filepath: Path to input audio file
        """
        self.filepath = Path(filepath)
        if not self.filepath.exists():
            raise FileNotFoundError(f"Audio file not found: {filepath}")

        self._audio = None
        self._load_audio()

    def _load_audio(self):
        """Load audio file using pydub."""
        try:
            from pydub import AudioSegment
            self._audio = AudioSegment.from_file(str(self.filepath))
        except ImportError:
            raise ImportError("pydub is required. Install with: pip install pydub")
        except Exception as e:
            raise ValueError(f"Failed to load audio file: {e}")

    @staticmethod
    def _parse_timestamp(ts: str) -> int:
        """
        Parse timestamp string to milliseconds.

        Args:
            ts: Timestamp string (HH:MM:SS, MM:SS, or seconds)

        Returns:
            Milliseconds
        """
        if isinstance(ts, (int, float)):
            return int(ts * 1000) if ts < 1000 else int(ts)

        ts = str(ts).strip()

        # Try HH:MM:SS.ms or HH:MM:SS
        match = re.match(r'^(\d+):(\d{2}):(\d{2})(?:\.(\d+))?$', ts)
        if match:
            h, m, s = int(match.group(1)), int(match.group(2)), int(match.group(3))
            ms = int(match.group(4) or 0)
            return (h * 3600 + m * 60 + s) * 1000 + ms

        # Try MM:SS.ms or MM:SS
        match = re.match(r'^(\d+):(\d{2})(?:\.(\d+))?$', ts)
        if match:
            m, s = int(match.group(1)), int(match.group(2))
            ms = int(match.group(3) or 0)
            return (m * 60 + s) * 1000 + ms

        # Try seconds.ms
        match = re.match(r'^(\d+)(?:\.(\d+))?$', ts)
        if match:
            s = int(match.group(1))
            ms = int(match.group(2) or 0)
            return s * 1000 + ms

        raise ValueError(f"Invalid timestamp format: {ts}")

    def trim(
        self,
        start: Optional[Union[str, int]] = None,
        end: Optional[Union[str, int]] = None,
        start_ms: Optional[int] = None,
        end_ms: Optional[int] = None
    ) -> 'AudioTrimmer':
        """
        Trim audio to segment.

        Args:
            start: Start timestamp (HH:MM:SS, MM:SS, or seconds)
            end: End timestamp
            start_ms: Start position in milliseconds
            end_ms: End position in milliseconds

        Returns:
            Self for chaining
        """
        # Parse timestamps
        if start is not None:
            start_ms = self._parse_timestamp(start)
        if end is not None:
            end_ms = self._parse_timestamp(end)

        # Default values
        if start_ms is None:
            start_ms = 0
        if end_ms is None:
            end_ms = len(self._audio)

        # Validate
        if start_ms < 0:
            start_ms = 0
        if end_ms > len(self._audio):
            end_ms = len(self._audio)
        if start_ms >= end_ms:
            raise ValueError("Start must be before end")

        self._audio = self._audio[start_ms:end_ms]
        return self

    def fade_in(self, duration_ms: int) -> 'AudioTrimmer':
        """
        Apply fade in effect.

        Args:
            duration_ms: Fade duration in milliseconds

        Returns:
            Self for chaining
        """
        if duration_ms > len(self._audio):
            duration_ms = len(self._audio)

        self._audio = self._audio.fade_in(duration_ms)
        return self

    def fade_out(self, duration_ms: int) -> 'AudioTrimmer':
        """
        Apply fade out effect.

        Args:
            duration_ms: Fade duration in milliseconds

        Returns:
            Self for chaining
        """
        if duration_ms > len(self._audio):
            duration_ms = len(self._audio)

        self._audio = self._audio.fade_out(duration_ms)
        return self

    def speed(self, factor: float) -> 'AudioTrimmer':
        """
        Change playback speed (affects pitch).

        Args:
            factor: Speed multiplier (1.5 = 50% faster, 0.5 = half speed)

        Returns:
            Self for chaining
        """
        if factor <= 0:
            raise ValueError("Speed factor must be positive")

        # Change frame rate to adjust speed
        new_frame_rate = int(self._audio.frame_rate * factor)
        self._audio = self._audio._spawn(
            self._audio.raw_data,
            overrides={'frame_rate': new_frame_rate}
        ).set_frame_rate(self._audio.frame_rate)

        return self

    def reverse(self) -> 'AudioTrimmer':
        """
        Reverse the audio.

        Returns:
            Self for chaining
        """
        self._audio = self._audio.reverse()
        return self

    def loop(self, times: int) -> 'AudioTrimmer':
        """
        Loop the audio N times.

        Args:
            times: Number of times to repeat

        Returns:
            Self for chaining
        """
        if times < 1:
            raise ValueError("Times must be at least 1")

        self._audio = self._audio * times
        return self

    def gain(self, db: float) -> 'AudioTrimmer':
        """
        Adjust volume by dB.

        Args:
            db: Volume change in decibels (positive = louder)

        Returns:
            Self for chaining
        """
        self._audio = self._audio + db
        return self

    def normalize(self, target_dbfs: float = -3.0) -> 'AudioTrimmer':
        """
        Normalize audio to target level.

        Args:
            target_dbfs: Target level in dBFS

        Returns:
            Self for chaining
        """
        change_in_dbfs = target_dbfs - self._audio.dBFS
        self._audio = self._audio.apply_gain(change_in_dbfs)
        return self

    def add_silence_start(self, duration_ms: int) -> 'AudioTrimmer':
        """
        Add silence at the start.

        Args:
            duration_ms: Silence duration in milliseconds

        Returns:
            Self for chaining
        """
        from pydub import AudioSegment
        silence = AudioSegment.silent(
            duration=duration_ms,
            frame_rate=self._audio.frame_rate
        )
        self._audio = silence + self._audio
        return self

    def add_silence_end(self, duration_ms: int) -> 'AudioTrimmer':
        """
        Add silence at the end.

        Args:
            duration_ms: Silence duration in milliseconds

        Returns:
            Self for chaining
        """
        from pydub import AudioSegment
        silence = AudioSegment.silent(
            duration=duration_ms,
            frame_rate=self._audio.frame_rate
        )
        self._audio = self._audio + silence
        return self

    def strip_silence(
        self,
        threshold: float = -50.0,
        chunk_size: int = 10,
        min_silence_len: int = 100
    ) -> 'AudioTrimmer':
        """
        Strip leading and trailing silence.

        Args:
            threshold: Silence threshold in dBFS
            chunk_size: Analysis chunk size in ms
            min_silence_len: Minimum silence length to strip

        Returns:
            Self for chaining
        """
        from pydub.silence import detect_leading_silence

        # Strip leading silence
        start_trim = detect_leading_silence(self._audio, silence_threshold=threshold, chunk_size=chunk_size)

        # Strip trailing silence
        reversed_audio = self._audio.reverse()
        end_trim = detect_leading_silence(reversed_audio, silence_threshold=threshold, chunk_size=chunk_size)

        if start_trim + end_trim < len(self._audio):
            self._audio = self._audio[start_trim:len(self._audio) - end_trim]

        return self

    def overlay(
        self,
        other_file: str,
        position_ms: int = 0,
        volume: float = 0,
        loop: bool = False
    ) -> 'AudioTrimmer':
        """
        Overlay another audio file.

        Args:
            other_file: Path to audio file to overlay
            position_ms: Position to start overlay
            volume: Volume adjustment for overlay (dB)
            loop: Loop overlay to fill duration

        Returns:
            Self for chaining
        """
        from pydub import AudioSegment

        other = AudioSegment.from_file(other_file)

        # Adjust volume
        if volume != 0:
            other = other + volume

        # Loop if needed
        if loop:
            remaining = len(self._audio) - position_ms
            if len(other) < remaining:
                repetitions = (remaining // len(other)) + 1
                other = other * repetitions
            other = other[:remaining]

        self._audio = self._audio.overlay(other, position=position_ms)
        return self

    def get_duration_ms(self) -> int:
        """Get current audio duration in milliseconds."""
        return len(self._audio)

    def get_duration_str(self) -> str:
        """Get current audio duration as formatted string."""
        total_seconds = len(self._audio) / 1000
        hours = int(total_seconds // 3600)
        minutes = int((total_seconds % 3600) // 60)
        seconds = total_seconds % 60

        if hours > 0:
            return f"{hours}:{minutes:02d}:{seconds:05.2f}"
        else:
            return f"{minutes}:{seconds:05.2f}"

    def save(
        self,
        output: str,
        format: Optional[str] = None,
        bitrate: int = 192
    ) -> str:
        """
        Save audio to file.

        Args:
            output: Output file path
            format: Output format (optional, from extension)
            bitrate: Bitrate for lossy formats (kbps)

        Returns:
            Path to saved file
        """
        output_path = Path(output)
        output_path.parent.mkdir(parents=True, exist_ok=True)

        if format is None:
            format = output_path.suffix.lstrip('.').lower()

        # Export parameters
        params = {}
        if format in ('mp3', 'ogg', 'm4a'):
            params['bitrate'] = f"{bitrate}k"

        self._audio.export(str(output_path), format=format, **params)
        return str(output_path)

    @classmethod
    def concatenate(
        cls,
        files: List[str],
        output: str,
        format: Optional[str] = None,
        bitrate: int = 192
    ) -> str:
        """
        Concatenate multiple audio files.

        Args:
            files: List of input file paths
            output: Output file path
            format: Output format
            bitrate: Bitrate for lossy formats

        Returns:
            Path to saved file
        """
        from pydub import AudioSegment

        if not files:
            raise ValueError("No files to concatenate")

        combined = AudioSegment.empty()
        for filepath in files:
            segment = AudioSegment.from_file(filepath)
            combined += segment

        output_path = Path(output)
        output_path.parent.mkdir(parents=True, exist_ok=True)

        if format is None:
            format = output_path.suffix.lstrip('.').lower()

        params = {}
        if format in ('mp3', 'ogg', 'm4a'):
            params['bitrate'] = f"{bitrate}k"

        combined.export(str(output_path), format=format, **params)
        return str(output_path)

    @classmethod
    def concatenate_with_crossfade(
        cls,
        files: List[str],
        output: str,
        crossfade_ms: int = 1000,
        format: Optional[str] = None,
        bitrate: int = 192
    ) -> str:
        """
        Concatenate files with crossfade transitions.

        Args:
            files: List of input file paths
            output: Output file path
            crossfade_ms: Crossfade duration in milliseconds
            format: Output format
            bitrate: Bitrate for lossy formats

        Returns:
            Path to saved file
        """
        from pydub import AudioSegment

        if not files:
            raise ValueError("No files to concatenate")

        combined = AudioSegment.from_file(files[0])

        for filepath in files[1:]:
            segment = AudioSegment.from_file(filepath)
            combined = combined.append(segment, crossfade=crossfade_ms)

        output_path = Path(output)
        output_path.parent.mkdir(parents=True, exist_ok=True)

        if format is None:
            format = output_path.suffix.lstrip('.').lower()

        params = {}
        if format in ('mp3', 'ogg', 'm4a'):
            params['bitrate'] = f"{bitrate}k"

        combined.export(str(output_path), format=format, **params)
        return str(output_path)


def main():
    """CLI entry point."""
    parser = argparse.ArgumentParser(
        description='Cut, trim, and edit audio segments',
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  %(prog)s --input podcast.mp3 --output segment.mp3 --start 05:30 --end 10:00
  %(prog)s --input song.mp3 --output faded.mp3 --fade-in 3000 --fade-out 5000
  %(prog)s --input lecture.mp3 --output fast.mp3 --speed 1.5
  %(prog)s --concat file1.mp3 file2.mp3 file3.mp3 --output merged.mp3
        """
    )

    parser.add_argument('--input', '-i', help='Input audio file')
    parser.add_argument('--output', '-o', required=True, help='Output file path')
    parser.add_argument('--start', '-s', help='Start timestamp (HH:MM:SS or MM:SS)')
    parser.add_argument('--end', '-e', help='End timestamp')
    parser.add_argument('--fade-in', type=int, help='Fade in duration (ms)')
    parser.add_argument('--fade-out', type=int, help='Fade out duration (ms)')
    parser.add_argument('--speed', type=float, default=1.0, help='Speed multiplier')
    parser.add_argument('--gain', type=float, default=0, help='Volume adjustment (dB)')
    parser.add_argument('--normalize', type=float, help='Normalize to dBFS level')
    parser.add_argument('--reverse', action='store_true', help='Reverse audio')
    parser.add_argument('--loop', type=int, help='Loop N times')
    parser.add_argument('--concat', nargs='+', help='Files to concatenate')
    parser.add_argument('--crossfade', type=int, default=0, help='Crossfade duration (ms)')
    parser.add_argument('--bitrate', type=int, default=192, help='Output bitrate (kbps)')
    parser.add_argument('--segments', help='Multiple segments: "00:00-05:00,10:00-15:00"')
    parser.add_argument('--output-dir', help='Output directory for multiple segments')

    args = parser.parse_args()

    # Concatenation mode
    if args.concat:
        if args.crossfade > 0:
            output = AudioTrimmer.concatenate_with_crossfade(
                args.concat, args.output,
                crossfade_ms=args.crossfade,
                bitrate=args.bitrate
            )
        else:
            output = AudioTrimmer.concatenate(
                args.concat, args.output,
                bitrate=args.bitrate
            )
        print(f"Concatenated {len(args.concat)} files -> {output}")
        return

    # Single file mode
    if not args.input:
        parser.error("--input is required (unless using --concat)")

    # Multiple segments mode
    if args.segments:
        if not args.output_dir:
            parser.error("--output-dir is required when using --segments")

        Path(args.output_dir).mkdir(parents=True, exist_ok=True)
        segment_pairs = args.segments.split(',')

        for i, segment in enumerate(segment_pairs):
            start, end = segment.strip().split('-')
            trimmer = AudioTrimmer(args.input)
            trimmer.trim(start=start.strip(), end=end.strip())

            if args.fade_in:
                trimmer.fade_in(args.fade_in)
            if args.fade_out:
                trimmer.fade_out(args.fade_out)

            output_file = Path(args.output_dir) / f"segment_{i+1:02d}.mp3"
            trimmer.save(str(output_file), bitrate=args.bitrate)
            print(f"Segment {i+1}: {start.strip()} - {end.strip()} -> {output_file}")

        return

    # Standard trimming mode
    trimmer = AudioTrimmer(args.input)

    # Apply operations
    if args.start or args.end:
        trimmer.trim(start=args.start, end=args.end)

    if args.speed != 1.0:
        trimmer.speed(args.speed)

    if args.reverse:
        trimmer.reverse()

    if args.loop:
        trimmer.loop(args.loop)

    if args.gain != 0:
        trimmer.gain(args.gain)

    if args.normalize is not None:
        trimmer.normalize(args.normalize)

    if args.fade_in:
        trimmer.fade_in(args.fade_in)

    if args.fade_out:
        trimmer.fade_out(args.fade_out)

    # Save
    output = trimmer.save(args.output, bitrate=args.bitrate)
    print(f"Saved: {output} (duration: {trimmer.get_duration_str()})")


if __name__ == "__main__":
    main()