stt_speechmatics_speaker_mapper.py

#!/usr/bin/env -S uv run
# /// script
# dependencies = [
#   "instructor>=1.0.0",
#   "pydantic>=2.0.0",
#   "openai>=1.0.0",
# ]
# requires-python = ">=3.11"
# ///
"""
Speechmatics Speaker Name Mapper

Post-processing tool to replace speaker labels (S1, S2, S3) with actual names
in Speechmatics transcription JSON files. Uses recursive traversal to handle
any JSON structure, making it future-proof and format-agnostic.

Features:
- LLM-assisted speaker detection with multiple provider support
- Interactive mapping with AI suggestions as defaults
- Audio preview: hear samples of each speaker during mapping
- Verification mode: review and correct existing mappings with audio
- Speaker audio extraction: save speaker segments to separate files

Usage:
    # Detect speakers
    ./stt_speechmatics_speaker_mapper.py --detect audio.speechmatics.json

    # LLM-assisted interactive (AI suggestions + audio preview)
    ./stt_speechmatics_speaker_mapper.py --llm-interactive gpt-4o-mini audio.speechmatics.json

    # Preview audio samples for a speaker
    ./stt_speechmatics_speaker_mapper.py --preview-speaker S1 audio.speechmatics.json

    # Map via inline comma-separated names
    ./stt_speechmatics_speaker_mapper.py -m "Alice,Bob" audio.speechmatics.json

    # Interactive mapping (manual)
    ./stt_speechmatics_speaker_mapper.py --interactive audio.speechmatics.json

Requirements for audio features:
    - ffmpeg (for audio extraction)
    - mpv, ffplay, or mplayer (for playback with seeking)
"""

import argparse
import sys
import json
import os
import re
import shutil
import tempfile
import subprocess
from typing import Dict, List, Optional, Tuple

# Optional LLM detection support
try:
    import instructor
    from pydantic import BaseModel, Field, ConfigDict
    from openai import OpenAI
    INSTRUCTOR_AVAILABLE = True
except ImportError:
    INSTRUCTOR_AVAILABLE = False
    instructor = None
    BaseModel = None
    Field = None
    ConfigDict = None
    OpenAI = None

# ----------------------------------------------------------------------
# Model Shortcuts - Map common names to full provider/model strings
# ----------------------------------------------------------------------
MODEL_SHORTCUTS = {
    # OpenAI models (best structured output support)
    '4o-mini': 'openai/gpt-4o-mini',
    'gpt-4o-mini': 'openai/gpt-4o-mini',
    '4o': 'openai/gpt-4o',
    'gpt-4o': 'openai/gpt-4o',
    '4.1': 'openai/gpt-4.1',
    'gpt-4.1': 'openai/gpt-4.1',
    '4.1-mini': 'openai/gpt-4.1-mini',
    'gpt-4.1-mini': 'openai/gpt-4.1-mini',
    'o1': 'openai/o1',
    'o3-mini': 'openai/o3-mini',

    # Anthropic Claude
    'sonnet': 'anthropic/claude-sonnet-4-5',
    'claude-sonnet': 'anthropic/claude-sonnet-4-5',
    'opus': 'anthropic/claude-opus-4-1',
    'claude-opus': 'anthropic/claude-opus-4-1',
    'haiku': 'anthropic/claude-3-5-haiku',
    'claude-haiku': 'anthropic/claude-3-5-haiku',

    # Google Gemini
    'gemini': 'google/gemini-2.5-flash',
    'gemini-flash': 'google/gemini-2.5-flash',
    'gemini-pro': 'google/gemini-2.0-pro-experimental',

    # Groq (ultra-fast inference)
    'llama': 'groq/llama-3.3-70b-versatile',
    'llama3.3': 'groq/llama-3.3-70b-versatile',

    # DeepSeek
    'deepseek': 'deepseek/deepseek-v3.2-exp',

    # Ollama (local deployment)
    'ollama': 'ollama/llama3.2',
    'smollm2': 'ollama/smollm2:1.7b',
    'smollm2:1.7b': 'ollama/smollm2:1.7b',
    'smollm2:360m': 'ollama/smollm2:360m',
}


def resolve_model_shortcut(model_string: str) -> str:
    """Resolve model shortcut to full provider/model string."""
    if '/' in model_string:
        return model_string
    model_lower = model_string.lower()
    return MODEL_SHORTCUTS.get(model_lower, model_string)


# ----------------------------------------------------------------------
# META Message Helper
# ----------------------------------------------------------------------
def get_meta_message(args):
    """Get META warning message for STT transcripts."""
    if getattr(args, 'no_meta_message', False) or getattr(args, 'disable_meta_message', False):
        return ""
    if os.environ.get('STT_META_MESSAGE_DISABLE', '').lower() in ('1', 'true', 'yes'):
        return ""
    custom_message = os.environ.get('STT_META_MESSAGE', '').strip()
    if custom_message:
        return f"---\nmeta: {custom_message}\n---\n"

    default_message = (
        "THIS IS AN AUTOMATED SPEECH-TO-TEXT (STT) TRANSCRIPT AND MAY CONTAIN TRANSCRIPTION ERRORS. "
        "This transcript was generated by automated speech recognition technology and should be treated "
        "as a rough transcription for reference purposes. Common types of errors include: incorrect word "
        "recognition (especially homophones, proper nouns, technical terminology, or words in noisy audio "
        "conditions), missing or incorrect punctuation, speaker misidentification in multi-speaker scenarios, "
        "and timing inaccuracies. For best comprehension and to mentally correct potential errors, please consider: "
        "the broader conversational context, relevant domain knowledge, technical background of the subject matter, "
        "and any supplementary information about the speakers or topic. This transcript is intended to convey "
        "the general content and flow of the conversation rather than serving as a verbatim, word-perfect record. "
        "When critical accuracy is required, please verify important details against the original audio source."
    )
    return f"---\nmeta: {default_message}\n---\n"


# ----------------------------------------------------------------------
# Verbosity-aware logger
# ----------------------------------------------------------------------
def _should_log(args, level_threshold):
    return getattr(args, "verbose", 0) >= level_threshold and not getattr(args, "quiet", False)

def log_error(args, message):
    print(f"ERROR: {message}", file=sys.stderr)

def log_warning(args, message):
    if _should_log(args, 0):
        print(f"WARNING: {message}", file=sys.stderr)

def log_info(args, message):
    if _should_log(args, 1):
        print(f"INFO: {message}", file=sys.stderr)

def log_debug(args, message):
    if _should_log(args, 5):
        print(f"DEBUG: {message}", file=sys.stderr)


# ----------------------------------------------------------------------
# About File Helper
# ----------------------------------------------------------------------

def get_about_file_path(input_json: str) -> str:
    """Generate about file path from input JSON path."""
    if input_json.endswith('.speechmatics.json'):
        base_audio = input_json[:-len('.speechmatics.json')]
    else:
        base_audio = input_json
    return f"{base_audio}.about.md"


def get_about_file_content(input_json: str) -> Optional[str]:
    """Load .about.md file content if it exists."""
    about_path = get_about_file_path(input_json)
    if os.path.exists(about_path):
        try:
            with open(about_path, 'r') as f:
                return f.read().strip()
        except Exception:
            return None
    return None


DIRECTORY_CONTEXT_FILENAME = "SPEAKER.CONTEXT.md"


def find_directory_context_file(input_json: str) -> Optional[str]:
    """Find SPEAKER.CONTEXT.md in same directory or parent directories."""
    if input_json.endswith('.speechmatics.json'):
        base_audio = input_json[:-len('.speechmatics.json')]
    else:
        base_audio = input_json

    original_dir = os.path.dirname(os.path.abspath(base_audio)) or '.'
    resolved_dir = os.path.dirname(os.path.realpath(base_audio)) or '.'

    dirs_to_check = []
    for start_dir in [original_dir, resolved_dir]:
        current = start_dir
        while current:
            if current not in dirs_to_check:
                dirs_to_check.append(current)
            parent = os.path.dirname(current)
            if parent == current:
                break
            current = parent

    for dir_path in dirs_to_check:
        context_path = os.path.join(dir_path, DIRECTORY_CONTEXT_FILENAME)
        if os.path.exists(context_path):
            return context_path
    return None


def get_directory_context_content(input_json: str) -> tuple[Optional[str], Optional[str]]:
    """Load directory context file content if it exists."""
    context_path = find_directory_context_file(input_json)
    if context_path:
        try:
            with open(context_path, 'r') as f:
                return f.read().strip(), context_path
        except Exception:
            return None, None
    return None, None


# ----------------------------------------------------------------------
# Audio Preview Functions
# ----------------------------------------------------------------------

def find_audio_player() -> Tuple[Optional[str], List[str]]:
    """Find available audio player with seeking support."""
    players = [
        ('mpv', ['mpv', '--no-video', '--term-osd-bar']),
        ('ffplay', ['ffplay', '-nodisp', '-autoexit']),
        ('mplayer', ['mplayer', '-vo', 'null']),
    ]
    for name, cmd in players:
        if shutil.which(cmd[0]):
            return name, cmd
    return None, []


def find_ffmpeg() -> Optional[str]:
    """Check if ffmpeg is available."""
    return shutil.which('ffmpeg')


def get_audio_file_path(input_json: str) -> str:
    """Derive audio file path from JSON path."""
    path = input_json
    for suffix in ['.speechmatics.mapped.json', '.speechmatics.json', '.mapped.json']:
        if path.endswith(suffix):
            return path[:-len(suffix)]
    if path.endswith('.json'):
        return path[:-5]
    return path


def get_speaker_utterances(json_data: dict, speaker_label: str) -> List[dict]:
    """
    Get all utterances for a specific speaker with timing info.

    Speechmatics format: results array with 'speaker' field on words.
    We need to group consecutive words by speaker into utterances.
    """
    results = json_data.get('results', [])
    utterances = []
    current_utterance = None

    for item in results:
        if item.get('type') != 'word':
            continue

        speaker = item.get('speaker', 'UU')
        if speaker != speaker_label:
            # Flush current utterance if we were tracking one
            if current_utterance:
                utterances.append(current_utterance)
                current_utterance = None
            continue

        # This word is from our target speaker
        start_time = item.get('start_time', 0)
        end_time = item.get('end_time', 0)
        content = ''
        if item.get('alternatives'):
            content = item['alternatives'][0].get('content', '')

        if current_utterance is None:
            # Start new utterance
            current_utterance = {
                'start': int(start_time * 1000),  # Convert to ms
                'end': int(end_time * 1000),
                'text': content
            }
        else:
            # Extend current utterance
            current_utterance['end'] = int(end_time * 1000)
            current_utterance['text'] += ' ' + content

    # Flush final utterance
    if current_utterance:
        utterances.append(current_utterance)

    return utterances


def format_duration(ms: int) -> str:
    """Format milliseconds as human-readable duration."""
    seconds = ms / 1000
    if seconds < 60:
        return f"{seconds:.1f}s"
    minutes = int(seconds // 60)
    secs = seconds % 60
    return f"{minutes}m {secs:.0f}s"


def extract_speaker_audio(
    audio_file: str,
    utterances: List[dict],
    output_file: str,
    max_samples: int = 10,
    max_duration_per_sample: float = 8.0,
    silence_gap: float = 0.3,
    args=None
) -> Tuple[bool, str]:
    """Extract and concatenate speaker audio samples using ffmpeg."""
    if not utterances:
        return False, "No utterances found for speaker"

    ffmpeg = find_ffmpeg()
    if not ffmpeg:
        return False, "ffmpeg not found. Install with: sudo pacman -S ffmpeg"

    if not os.path.exists(audio_file):
        return False, f"Audio file not found: {audio_file}"

    # Select samples
    selected = []
    for utt in utterances[:max_samples]:
        start_ms = utt.get('start', 0)
        end_ms = utt.get('end', 0)
        duration_s = (end_ms - start_ms) / 1000

        if duration_s > max_duration_per_sample:
            end_ms = start_ms + int(max_duration_per_sample * 1000)

        selected.append({
            'start': start_ms / 1000,
            'end': end_ms / 1000,
            'text': utt.get('text', '')[:50]
        })

    if not selected:
        return False, "No samples selected"

    # Build ffmpeg filter_complex
    filter_parts = []
    concat_inputs = []

    for i, sample in enumerate(selected):
        label = f"a{i}"
        filter_parts.append(
            f"[0]atrim=start={sample['start']:.3f}:end={sample['end']:.3f},"
            f"asetpts=PTS-STARTPTS[{label}]"
        )
        concat_inputs.append(f"[{label}]")

        if i < len(selected) - 1 and silence_gap > 0:
            silence_label = f"s{i}"
            filter_parts.append(
                f"anullsrc=r=44100:cl=stereo,atrim=0:{silence_gap:.2f}[{silence_label}]"
            )
            concat_inputs.append(f"[{silence_label}]")

    n_segments = len(concat_inputs)
    filter_parts.append(
        f"{''.join(concat_inputs)}concat=n={n_segments}:v=0:a=1[out]"
    )

    filter_complex = ';'.join(filter_parts)

    cmd = [
        ffmpeg,
        '-i', audio_file,
        '-filter_complex', filter_complex,
        '-map', '[out]',
        '-y',
        '-loglevel', 'error',
        output_file
    ]

    try:
        log_debug(args, f"Running ffmpeg with {len(selected)} samples")
        result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)

        if result.returncode != 0:
            error_msg = result.stderr.strip() if result.stderr else "Unknown error"
            return False, f"ffmpeg failed: {error_msg}"

        total_duration = sum(s['end'] - s['start'] for s in selected)
        return True, f"Extracted {len(selected)} samples ({format_duration(int(total_duration * 1000))})"

    except subprocess.TimeoutExpired:
        return False, "ffmpeg timed out"
    except Exception as e:
        return False, f"ffmpeg error: {e}"


def play_audio_file(
    filepath: str,
    player_name: str = None,
    player_cmd: List[str] = None,
    args=None
) -> bool:
    """Play audio file with seeking-capable terminal player."""
    if player_cmd is None:
        player_name, player_cmd = find_audio_player()

    if not player_cmd:
        log_error(args, "No audio player found. Install mpv: sudo pacman -S mpv")
        return False

    cmd = player_cmd + [filepath]

    if player_name == 'mpv':
        hint = "mpv: ←/→ seek 5s, ↑/↓ seek 1m, space=pause, q=quit"
    elif player_name == 'ffplay':
        hint = "ffplay: ←/→ seek 10s, space=pause, q=quit"
    else:
        hint = f"{player_name}: use arrow keys to seek, q=quit"

    print(f"→ Playing ({hint})", file=sys.stderr)

    try:
        result = subprocess.run(cmd, check=False)
        return result.returncode == 0
    except KeyboardInterrupt:
        print("", file=sys.stderr)
        return True
    except Exception as e:
        log_error(args, f"Playback failed: {e}")
        return False


def preview_speaker_audio(
    audio_file: str,
    json_data: dict,
    speaker_label: str,
    speaker_name: str = None,
    max_samples: int = 10,
    args=None
) -> bool:
    """Preview audio samples for a speaker."""
    display_name = speaker_name or f"Speaker {speaker_label}"

    utterances = get_speaker_utterances(json_data, speaker_label)

    if not utterances:
        print(f"No utterances found for {display_name}", file=sys.stderr)
        return False

    total_duration = sum(u.get('end', 0) - u.get('start', 0) for u in utterances)

    print(f"\nExtracting samples for {display_name}...", file=sys.stderr)
    print(f"  Found {len(utterances)} utterances ({format_duration(total_duration)})", file=sys.stderr)

    player_name, player_cmd = find_audio_player()
    if not player_cmd:
        print("ERROR: No audio player found. Install mpv: sudo pacman -S mpv", file=sys.stderr)
        return False

    with tempfile.NamedTemporaryFile(suffix='.mp3', delete=False) as tmp:
        tmp_path = tmp.name

    try:
        success, message = extract_speaker_audio(
            audio_file,
            utterances,
            tmp_path,
            max_samples=max_samples,
            args=args
        )

        if not success:
            print(f"ERROR: {message}", file=sys.stderr)
            return False

        print(f"  {message}", file=sys.stderr)
        return play_audio_file(tmp_path, player_name, player_cmd, args)

    finally:
        try:
            os.unlink(tmp_path)
        except OSError:
            pass


# ----------------------------------------------------------------------
# Core JSON Traversal Functions
# ----------------------------------------------------------------------

def detect_speakers_in_json(json_obj, found=None):
    """
    Recursively find all unique values associated with "speaker" keys.

    For Speechmatics, speaker labels are S1, S2, S3, etc.
    UU is used for unidentified speakers.
    """
    if found is None:
        found = set()

    if isinstance(json_obj, dict):
        for key, value in json_obj.items():
            if key == "speaker" and isinstance(value, str):
                found.add(value)
            else:
                detect_speakers_in_json(value, found)
    elif isinstance(json_obj, list):
        for item in json_obj:
            detect_speakers_in_json(item, found)

    return found


def replace_speakers_recursive(obj, speaker_map):
    """Recursively traverse JSON and replace all "speaker" key values."""
    if isinstance(obj, dict):
        result = {}
        for key, value in obj.items():
            if key == "speaker" and isinstance(value, str):
                result[key] = speaker_map.get(value, value)
            else:
                result[key] = replace_speakers_recursive(value, speaker_map)
        return result

    elif isinstance(obj, list):
        return [replace_speakers_recursive(item, speaker_map) for item in obj]

    else:
        return obj


def find_transcript_segments(json_obj):
    """
    Find word results in Speechmatics JSON and group by speaker.

    Speechmatics uses 'results' array with individual words.
    We group consecutive words by speaker to create utterance-like segments.
    """
    results = json_obj.get('results', [])

    if not results:
        return []

    segments = []
    current_segment = None

    for item in results:
        if item.get('type') != 'word':
            continue

        speaker = item.get('speaker', 'UU')
        content = ''
        if item.get('alternatives'):
            content = item['alternatives'][0].get('content', '')

        if current_segment is None or current_segment.get('speaker') != speaker:
            # Flush previous segment
            if current_segment and current_segment.get('text'):
                segments.append(current_segment)
            current_segment = {
                'speaker': speaker,
                'text': content
            }
        else:
            # Append to current segment
            if content:
                current_segment['text'] += ' ' + content

    # Flush final segment
    if current_segment and current_segment.get('text'):
        segments.append(current_segment)

    return segments


# ----------------------------------------------------------------------
# LLM-Assisted Speaker Detection (Optional)
# ----------------------------------------------------------------------

if INSTRUCTOR_AVAILABLE:
    class SpeakerMapping(BaseModel):
        """Individual speaker label to name mapping."""
        speaker_label: str = Field(
            description="Speaker label from transcript (e.g., 'S1', 'S2', 'UU')"
        )
        speaker_name: str = Field(
            description="Identified name or role for this speaker"
        )
        context: str = Field(
            description="Brief contextual information about this speaker",
            default=""
        )

    class SpeakerDetection(BaseModel):
        """Pydantic model for LLM speaker detection response."""
        model_config = ConfigDict(extra='allow')

        speakers: List[SpeakerMapping] = Field(
            description='List of speaker mappings. Must include one mapping for EACH detected speaker label.'
        )
        confidence: str = Field(
            description="Confidence level: low, medium, or high",
            default="medium"
        )
        reasoning: str = Field(
            description="Brief explanation of how speakers were identified",
            default=""
        )


def extract_transcript_sample(json_obj: dict, max_utterances: int = 20) -> str:
    """Extract strategic sample of transcript for LLM analysis."""
    segments = find_transcript_segments(json_obj)

    if not segments:
        return ""

    # Take first N segments
    sample_segments = segments[:max_utterances]

    # Format as readable transcript
    lines = []
    for seg in sample_segments:
        speaker = seg.get('speaker', 'Unknown')
        text = seg.get('text', '')
        lines.append(f"Speaker {speaker}: {text}")

    return '\n'.join(lines)


def detect_speakers_llm(
    provider_model: str,
    transcript_sample: str,
    detected_labels: List[str],
    endpoint: Optional[str] = None,
    args=None,
    input_json: Optional[str] = None
):
    """Detect speaker names using LLM via Instructor."""
    if not INSTRUCTOR_AVAILABLE:
        raise RuntimeError(
            "Instructor library not available. Install with: pip install instructor openai"
        )

    original_model = provider_model
    provider_model = resolve_model_shortcut(provider_model)

    if original_model != provider_model:
        log_debug(args, f"Resolved shortcut '{original_model}' → '{provider_model}'")

    log_debug(args, f"LLM provider: {provider_model}")
    log_debug(args, f"Detected labels: {detected_labels}")

    # Build prompt
    prompt = f"""Analyze this conversation transcript and identify the speakers.

DETECTED SPEAKERS: {', '.join(detected_labels)}

Note: Speechmatics uses S1, S2, S3, etc. for speaker labels. UU means unidentified speaker.

Your task is to create a mapping of each detected speaker label to their actual name or professional role.

CRITICAL WARNING - Avoid Address Confusion:
When someone says a name in their utterance, they are usually ADDRESSING that person, NOT identifying themselves.
- "Alice, what do you think?" → Speaker is NOT Alice, they are talking TO Alice
- "Bob, I agree with you" → Speaker is NOT Bob, they are responding TO Bob

Look for:
- Direct name mentions - but remember: the name mentioned is usually the ADDRESSEE, not the speaker
- Introductions ("I'm...", "My name is...") - these DO identify the speaker
- Professional roles if names aren't mentioned (Host, Guest, Expert, Interviewer)
"""

    # Add context files if available
    dir_context = None
    about_content = None

    if input_json:
        dir_context, dir_context_path = get_directory_context_content(input_json)
        if dir_context:
            if not getattr(args, 'quiet', False):
                print(f"Using directory context from: {dir_context_path}", file=sys.stderr)
            prompt += f"\nDIRECTORY CONTEXT:\n{dir_context}\n"

        about_content = get_about_file_content(input_json)
        if about_content:
            about_path = get_about_file_path(input_json)
            if not getattr(args, 'quiet', False):
                print(f"Using file context from: {about_path}", file=sys.stderr)
            prompt += f"\nFILE-SPECIFIC CONTEXT:\n{about_content}\n"

    prompt += f"""
TRANSCRIPT SAMPLE:
{transcript_sample}

You must provide a mapping for EACH detected speaker label ({', '.join(detected_labels)}) including:
1. speaker_label: The label (S1, S2, S3, etc.)
2. speaker_name: Their identified name or role (use "Unknown" if uncertain)
3. context: Brief contextual info about this speaker
"""

    try:
        if endpoint:
            log_info(args, f"Using custom endpoint: {endpoint}")
            base_client = OpenAI(base_url=endpoint, api_key="none")
            client = instructor.from_openai(base_client, mode=instructor.Mode.JSON)
            model = provider_model.split("/")[1] if "/" in provider_model else provider_model
        else:
            log_info(args, f"Using provider: {provider_model}")
            client = instructor.from_provider(provider_model, mode=instructor.Mode.TOOLS)
            model = provider_model.split("/")[1] if "/" in provider_model else provider_model

        log_debug(args, "Calling LLM...")
        result = client.chat.completions.create(
            model=model,
            messages=[{"role": "user", "content": prompt}],
            response_model=SpeakerDetection,
            max_retries=3
        )

        log_debug(args, f"LLM response - Confidence: {result.confidence}")
        log_debug(args, f"LLM response - Speakers: {result.speakers}")

        # Extract contexts before converting
        speaker_contexts = {mapping.speaker_label: mapping.context for mapping in result.speakers}

        # Convert to dict for compatibility
        result.speakers = {mapping.speaker_label: mapping.speaker_name for mapping in result.speakers}
        result.speaker_contexts = speaker_contexts

        return result

    except Exception as e:
        log_error(args, f"LLM detection failed: {e}")
        raise


def handle_llm_detection(args, json_data, detected_speakers):
    """Handle LLM-assisted speaker detection."""
    suggestions_path = get_suggestions_file_path(args.input_json)

    if args.llm_interactive and os.path.exists(suggestions_path) and not args.force:
        try:
            log_info(args, "Found cached suggestions file, loading...")
            _, ai_suggestions, metadata = load_suggestions_from_file(suggestions_path, args)
            speaker_contexts = metadata.get('speaker_contexts', {})
            return prompt_interactive_with_suggestions(
                detected_speakers,
                ai_suggestions,
                speaker_contexts,
                args.input_json,
                args,
                json_data=json_data
            )
        except (FileNotFoundError, ValueError) as e:
            log_warning(args, f"Failed to load suggestions file: {e}")

    provider_spec = args.llm_detect or args.llm_interactive or args.llm_detect_fallback

    if not provider_spec:
        provider_spec = "openai/gpt-4o-mini"
        log_info(args, f"No provider specified, using default: {provider_spec}")

    try:
        transcript_sample = extract_transcript_sample(
            json_data,
            max_utterances=args.llm_sample_size
        )

        if not transcript_sample:
            raise ValueError("No transcript segments found for LLM analysis")

        log_debug(args, f"Transcript sample ({len(transcript_sample)} chars)")

        log_info(args, "Analyzing transcript with LLM...")
        detection_result = detect_speakers_llm(
            provider_spec,
            transcript_sample,
            list(detected_speakers),
            endpoint=args.llm_endpoint,
            args=args,
            input_json=args.input_json
        )

        log_info(args, f"LLM confidence: {detection_result.confidence}")
        if detection_result.reasoning:
            log_info(args, f"LLM reasoning: {detection_result.reasoning}")

        # Save suggestions
        try:
            save_suggestions_to_file(
                suggestions_path,
                detected_speakers,
                detection_result.speakers,
                detection_result,
                provider_spec,
                args.input_json,
                args
            )
        except Exception as e:
            log_warning(args, f"Failed to save suggestions file: {e}")

        if args.llm_interactive:
            speaker_contexts = getattr(detection_result, 'speaker_contexts', {})
            return prompt_interactive_with_suggestions(
                detected_speakers,
                detection_result.speakers,
                speaker_contexts,
                args.input_json,
                args,
                json_data=json_data
            )
        else:
            speaker_map = detection_result.speakers
            for speaker, name in speaker_map.items():
                if name.lower() == "unknown":
                    log_warning(args, f"LLM could not identify speaker {speaker}")
            return speaker_map

    except Exception as e:
        log_error(args, f"LLM detection failed: {e}")

        if args.llm_detect_fallback:
            log_warning(args, "Falling back to manual interactive mode")
            return prompt_interactive_mapping(detected_speakers, args)
        else:
            raise


def show_command_help():
    """Show available commands and placeholders."""
    help_text = """
=== Interactive Commands ===

Special commands:
  skip              - Abort mapping (can rerun later)
  help              - Show this help message
  play              - Play entire audio file
  speak             - Preview audio samples for CURRENT speaker being prompted
  speak S1          - Preview audio samples for speaker S1 (or any label)
  about             - Edit about file with context (opens $EDITOR)
  !<command>        - Execute shell command with placeholders

Placeholders (use in ! commands):
  {audio} {a}       - Original audio file
  {text} {t}        - Base transcript (.txt)
  {json} {j}        - Base JSON (.speechmatics.json)
  {mapped-text} {mt} - Mapped transcript (output)
  {mapped-json} {mj} - Mapped JSON (output)

Press Enter to accept AI suggestion, or type a name to override.
"""
    print(help_text, file=sys.stderr)


def expand_command_placeholders(command: str, input_json: str) -> str:
    """Expand placeholders in command with actual file paths."""
    import shlex

    if input_json.endswith('.speechmatics.json'):
        base_audio = input_json[:-len('.speechmatics.json')]
    else:
        base_audio = input_json

    files = {
        '{audio}': base_audio,
        '{a}': base_audio,
        '{text}': f'{base_audio}.txt',
        '{t}': f'{base_audio}.txt',
        '{json}': input_json,
        '{j}': input_json,
        '{mapped-json}': f'{base_audio}.speechmatics.mapped.json',
        '{mj}': f'{base_audio}.speechmatics.mapped.json',
        '{mapped-text}': f'{base_audio}.speechmatics.mapped.txt',
        '{mt}': f'{base_audio}.speechmatics.mapped.txt',
        '{about}': f'{base_audio}.about.md',
        '{ab}': f'{base_audio}.about.md',
    }

    result = command
    for placeholder, filepath in files.items():
        if placeholder in result:
            quoted = shlex.quote(filepath)
            result = result.replace(placeholder, quoted)

    return result


def execute_command(command: str, input_json: str, args) -> bool:
    """Execute a shell command with placeholder expansion."""
    expanded = expand_command_placeholders(command, input_json)
    print(f"\n→ Executing: {expanded}", file=sys.stderr)

    try:
        result = subprocess.run(expanded, shell=True, check=False)
        if result.returncode != 0:
            log_warning(args, f"Command exited with code {result.returncode}")
            return False
        return True
    except Exception as e:
        log_error(args, f"Command execution failed: {e}")
        return False


def prompt_interactive_with_suggestions(
    detected_speakers: set,
    ai_suggestions: dict,
    speaker_contexts: dict,
    input_json: str,
    args,
    json_data: dict = None
) -> dict:
    """Interactive prompts with AI suggestions as defaults."""
    audio_file = get_audio_file_path(input_json)

    # Show all AI-detected mappings upfront
    print("\n=== AI-Detected Speaker Mappings ===", file=sys.stderr)
    for speaker in sorted(detected_speakers):
        suggestion = ai_suggestions.get(speaker, "Unknown")
        context = speaker_contexts.get(speaker, "")
        if context:
            print(f"{speaker} => {suggestion} # {context}", file=sys.stderr)
        else:
            print(f"{speaker} => {suggestion}", file=sys.stderr)

    print("\n=== Review and Confirm ===", file=sys.stderr)
    print("  Enter=accept | name=override | skip=abort | speak=hear speaker | help=commands", file=sys.stderr)
    print("", file=sys.stderr)

    speaker_map = {}

    for speaker in sorted(detected_speakers):
        suggestion = ai_suggestions.get(speaker, "Unknown")
        prompt_text = f"{speaker} => [{suggestion}]: "

        while True:
            try:
                user_input = input(prompt_text).strip()
            except (EOFError, KeyboardInterrupt):
                print("\n\nInterrupted - skipping speaker mapping.", file=sys.stderr)
                return None

            if user_input.lower() == 'skip':
                print("\nSkipping speaker mapping - no files will be created.", file=sys.stderr)
                return None

            elif user_input.lower() == 'help':
                show_command_help()
                continue

            elif user_input.lower() == 'play':
                try:
                    execute_command('play {audio}', input_json, args)
                except KeyboardInterrupt:
                    print("", file=sys.stderr)
                continue

            elif user_input.lower().startswith('speak'):
                if json_data is None:
                    print("ERROR: Audio preview not available", file=sys.stderr)
                    continue

                parts = user_input.split(None, 1)
                if len(parts) > 1:
                    target_speaker = parts[1].strip()
                    if target_speaker not in detected_speakers:
                        print(f"Unknown speaker: {target_speaker}", file=sys.stderr)
                        print(f"Available: {', '.join(sorted(detected_speakers))}", file=sys.stderr)
                        continue
                else:
                    target_speaker = speaker

                target_name = ai_suggestions.get(target_speaker, f"Speaker {target_speaker}")

                try:
                    preview_speaker_audio(
                        audio_file,
                        json_data,
                        target_speaker,
                        speaker_name=target_name,
                        args=args
                    )
                except KeyboardInterrupt:
                    print("", file=sys.stderr)
                print("", file=sys.stderr)
                continue

            elif user_input.lower() == 'about':
                about_path = get_about_file_path(input_json)
                editor = os.environ.get('EDITOR', os.environ.get('VISUAL', 'nano'))
                try:
                    print(f"\n→ Opening {about_path} in {editor}...", file=sys.stderr)
                    subprocess.run([editor, about_path], check=False)
                    if os.path.exists(about_path):
                        print(f"✓ About file saved: {about_path}", file=sys.stderr)
                    print("", file=sys.stderr)
                except Exception as e:
                    log_error(args, f"Failed to open editor: {e}")
                continue

            elif user_input.startswith('!'):
                command = user_input[1:].strip()
                if command:
                    try:
                        execute_command(command, input_json, args)
                    except KeyboardInterrupt:
                        print("", file=sys.stderr)
                continue

            else:
                break

        if user_input:
            speaker_map[speaker] = user_input
            log_debug(args, f"User override: {speaker} → {user_input}")
        else:
            if suggestion != "Unknown":
                speaker_map[speaker] = suggestion
                log_debug(args, f"Accepted AI suggestion: {speaker} → {suggestion}")
            else:
                log_warning(args, f"No name provided for {speaker}, keeping original")

    return speaker_map


# ----------------------------------------------------------------------
# Speaker Mapping Parsers
# ----------------------------------------------------------------------

def parse_speaker_map_inline(names_str, detected_speakers):
    """Parse comma-separated speaker names."""
    names = [n.strip() for n in names_str.split(',') if n.strip()]
    speakers_sorted = sorted(detected_speakers)

    speaker_map = {}
    for i, speaker in enumerate(speakers_sorted):
        if i < len(names):
            speaker_map[speaker] = names[i]

    return speaker_map


def parse_speaker_map_file(filepath, detected_speakers):
    """Parse speaker mapping file with auto-format detection."""
    with open(filepath, 'r') as f:
        lines = [line.strip() for line in f if line.strip() and not line.startswith('#')]

    if not lines:
        return {}

    # Detect format: does first line contain ':'?
    if ':' in lines[0]:
        # Key:value format
        speaker_map = {}
        for line in lines:
            if ':' not in line:
                continue
            key, value = line.split(':', 1)
            key = key.strip()
            value = value.strip()
            # Handle "Speaker S1" format
            if key.startswith('Speaker '):
                key = key[8:]
            speaker_map[key] = value
        return speaker_map
    else:
        # Sequential format
        speakers_sorted = sorted(detected_speakers)
        speaker_map = {}
        for i, name in enumerate(lines):
            if i < len(speakers_sorted):
                speaker_map[speakers_sorted[i]] = name.strip()
        return speaker_map


def prompt_interactive_mapping(detected_speakers, args):
    """Interactively prompt user for speaker names."""
    print("\n=== Detected Speakers ===", file=sys.stderr)
    speaker_map = {}

    for speaker in sorted(detected_speakers):
        prompt_text = f"Name for '{speaker}' (press Enter to keep): "
        name = input(prompt_text).strip()
        if name:
            speaker_map[speaker] = name
            log_debug(args, f"Mapped: {speaker} → {name}")

    return speaker_map


# ----------------------------------------------------------------------
# Output Generation
# ----------------------------------------------------------------------

def generate_txt_from_json(json_obj, args=None):
    """Generate formatted transcript TXT from JSON."""
    segments = find_transcript_segments(json_obj)

    if not segments:
        return ""

    lines = []

    if args:
        meta_message = get_meta_message(args)
        if meta_message:
            lines.append(meta_message.rstrip('\n'))

    for segment in segments:
        speaker = segment.get('speaker', 'Unknown')
        text = segment.get('text', '')
        lines.append(f"{speaker}:\t{text}")

    return '\n'.join(lines) + '\n'


def generate_output_path(input_path, extension=''):
    """Generate output path by inserting '.mapped' before final extension."""
    if input_path.endswith('.json'):
        base = input_path[:-5]
        return f"{base}.mapped{extension}"
    else:
        base, ext = os.path.splitext(input_path)
        return f"{base}.mapped{extension}"


# ----------------------------------------------------------------------
# Suggestions File I/O
# ----------------------------------------------------------------------

def get_suggestions_file_path(input_json_path):
    """Generate suggestions file path from input JSON path."""
    if input_json_path.endswith('.json'):
        base = input_json_path[:-5]
        return f"{base}.mapping-suggestions.json"
    else:
        return f"{input_json_path}.mapping-suggestions.json"


def save_suggestions_to_file(
    suggestions_path: str,
    detected_speakers: set,
    speaker_suggestions: dict,
    detection_result,
    model: str,
    input_file: str,
    args
):
    """Save LLM speaker suggestions to JSON file."""
    from datetime import datetime, timezone

    suggestions_data = {
        "detected_speakers": sorted(detected_speakers),
        "suggestions": speaker_suggestions,
        "speaker_contexts": getattr(detection_result, 'speaker_contexts', {}),
        "confidence": getattr(detection_result, 'confidence', 'unknown'),
        "reasoning": getattr(detection_result, 'reasoning', ''),
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "model": model,
        "input_file": input_file
    }

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

    log_info(args, f"Saved suggestions to: {suggestions_path}")


def load_suggestions_from_file(suggestions_path: str, args):
    """Load speaker suggestions from JSON file."""
    try:
        with open(suggestions_path, 'r') as f:
            data = json.load(f)
    except FileNotFoundError:
        raise FileNotFoundError(f"Suggestions file not found: {suggestions_path}")
    except json.JSONDecodeError as e:
        raise ValueError(f"Invalid JSON in suggestions file: {e}")

    required_fields = ['detected_speakers', 'suggestions']
    for field in required_fields:
        if field not in data:
            raise ValueError(f"Suggestions file missing required field: {field}")

    detected_speakers = data['detected_speakers']
    suggestions = data['suggestions']

    metadata = {
        'confidence': data.get('confidence', 'unknown'),
        'reasoning': data.get('reasoning', ''),
        'timestamp': data.get('timestamp', ''),
        'model': data.get('model', 'unknown'),
        'input_file': data.get('input_file', ''),
        'speaker_contexts': data.get('speaker_contexts', {})
    }

    log_info(args, f"Loaded suggestions from: {suggestions_path}")

    return detected_speakers, suggestions, metadata


# ----------------------------------------------------------------------
# Validation and Logging
# ----------------------------------------------------------------------

def validate_and_log_mapping(speaker_map, detected_speakers, args):
    """Validate speaker mapping and log coverage information."""
    mapped = set(speaker_map.keys())
    detected = set(detected_speakers)

    unmapped = detected - mapped
    extra = mapped - detected

    if unmapped:
        log_warning(args, f"Unmapped speakers (keeping original): {', '.join(sorted(unmapped))}")

    if extra:
        log_warning(args, f"Extra mappings for non-existent speakers: {', '.join(sorted(extra))}")

    log_info(args, f"Detected {len(detected)} speaker(s): {', '.join(sorted(detected))}")

    if speaker_map:
        log_info(args, "Applied mappings:")
        for speaker in sorted(speaker_map.keys()):
            log_info(args, f"  {speaker} → {speaker_map[speaker]}")


# ----------------------------------------------------------------------
# File I/O
# ----------------------------------------------------------------------

def write_json(filepath, data, args):
    """Write JSON data to file with optional META note."""
    meta_message_text = get_meta_message(args).replace("---\nmeta: ", "").replace("\n---\n", "").strip()
    if meta_message_text:
        data_with_meta = {
            "_meta_note": meta_message_text,
            **data
        }
        with open(filepath, 'w') as f:
            json.dump(data_with_meta, f, indent=2)
    else:
        with open(filepath, 'w') as f:
            json.dump(data, f, indent=2)
    log_info(args, f"Wrote JSON: {filepath}")


def write_txt(filepath, content, args):
    """Write text content to file."""
    with open(filepath, 'w') as f:
        f.write(content)
    log_info(args, f"Wrote TXT: {filepath}")


# ----------------------------------------------------------------------
# Argument Parsing
# ----------------------------------------------------------------------

def parse_args():
    """Parse command-line arguments."""
    parser = argparse.ArgumentParser(
        description="Replace speaker labels with names in Speechmatics JSON files",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  # Detect speakers in JSON
  %(prog)s --detect audio.speechmatics.json

  # LLM-assisted speaker detection (auto)
  %(prog)s --llm-detect openai/gpt-4o-mini audio.speechmatics.json
  %(prog)s --llm-detect ollama/llama3.2 audio.speechmatics.json

  # LLM-assisted interactive (AI suggestions as defaults)
  %(prog)s --llm-interactive openai/gpt-4o-mini audio.speechmatics.json

  # Map via comma-separated names (sorted order)
  %(prog)s -m "Alice,Bob,Charlie" audio.speechmatics.json

  # Map via file (auto-detects format)
  %(prog)s -M speakers.txt audio.speechmatics.json

  # Interactive mapping (manual)
  %(prog)s --interactive audio.speechmatics.json

  # Preview speaker audio
  %(prog)s --preview-speaker S1 audio.speechmatics.json

Speaker Labels:
  Speechmatics uses S1, S2, S3, etc. for speaker labels.
  UU is used for unidentified/unknown speakers.

Model Shortcuts:
  4o-mini, sonnet, gemini, llama, deepseek, smollm2:1.7b, etc.
        """
    )

    parser.add_argument(
        'input_json',
        help='Path to Speechmatics JSON file (e.g., audio.speechmatics.json)'
    )

    # Mapping sources (mutually exclusive)
    mapping_group = parser.add_mutually_exclusive_group()
    mapping_group.add_argument(
        '-m', '--speaker-map',
        help='Comma-separated speaker names (e.g., "Alice,Bob,Charlie")'
    )
    mapping_group.add_argument(
        '-M', '--speaker-map-file',
        help='Path to file with speaker mappings (auto-detects format)'
    )
    mapping_group.add_argument(
        '--interactive',
        action='store_true',
        help='Interactively prompt for speaker names'
    )
    mapping_group.add_argument(
        '--llm-detect',
        metavar='PROVIDER/MODEL',
        help='Automatically detect speaker names using LLM'
    )
    mapping_group.add_argument(
        '--llm-interactive',
        metavar='PROVIDER/MODEL',
        help='Interactive mode with AI-suggested speaker names as defaults'
    )
    mapping_group.add_argument(
        '--llm-detect-fallback',
        metavar='PROVIDER/MODEL',
        help='Try LLM detection, fall back to manual interactive if it fails'
    )

    # LLM configuration
    parser.add_argument(
        '--llm-endpoint',
        metavar='URL',
        help='Custom LLM endpoint URL (for remote Ollama or custom servers)'
    )
    parser.add_argument(
        '--llm-sample-size',
        type=int,
        default=20,
        metavar='N',
        help='Number of utterances to send to LLM for analysis (default: 20)'
    )

    # Output control
    parser.add_argument(
        '-o', '--output',
        help='Output base name (default: auto-generate with .mapped)'
    )
    parser.add_argument(
        '-f', '--force',
        action='store_true',
        help='Overwrite existing output files'
    )
    parser.add_argument(
        '--txt-only',
        action='store_true',
        help='Generate only .txt file (skip .json)'
    )
    parser.add_argument(
        '--json-only',
        action='store_true',
        help='Generate only .json file (skip .txt)'
    )
    parser.add_argument(
        '--detect',
        action='store_true',
        help='Only show detected speakers and exit (no processing)'
    )
    parser.add_argument(
        '--stdout-only',
        action='store_true',
        help='Output speaker mapping as JSON to stdout instead of files'
    )

    # Audio preview features
    parser.add_argument(
        '--preview-speaker',
        metavar='LABEL',
        help='Preview audio samples for a specific speaker label (e.g., S1, S2) and exit'
    )
    parser.add_argument(
        '--extract-speaker',
        metavar='LABEL',
        help='Extract audio samples for a speaker to a file (use with -o for output path)'
    )
    parser.add_argument(
        '--max-samples',
        type=int,
        default=10,
        metavar='N',
        help='Maximum number of audio samples to extract/preview (default: 10)'
    )

    # Logging
    parser.add_argument(
        '-v', '--verbose',
        action='count',
        default=0,
        help='Increase verbosity (-v=INFO, -vvvvv=DEBUG)'
    )
    parser.add_argument(
        '-q', '--quiet',
        action='store_true',
        help='Suppress all non-error output'
    )

    # META message control
    parser.add_argument(
        '--no-meta-message', '--disable-meta-message',
        action='store_true',
        dest='no_meta_message',
        help='Disable the META warning message'
    )

    return parser.parse_args()


# ----------------------------------------------------------------------
# Main
# ----------------------------------------------------------------------

def main():
    """Main execution flow."""
    args = parse_args()

    # Load input JSON
    try:
        with open(args.input_json, 'r') as f:
            json_data = json.load(f)
    except FileNotFoundError:
        log_error(args, f"File not found: {args.input_json}")
        sys.exit(1)
    except json.JSONDecodeError as e:
        log_error(args, f"Invalid JSON: {e}")
        sys.exit(1)

    log_debug(args, f"Loaded JSON from: {args.input_json}")

    # Detect speakers
    detected_speakers = detect_speakers_in_json(json_data)

    if not detected_speakers:
        log_error(args, "No speakers detected in JSON (no 'speaker' keys found)")
        sys.exit(1)

    log_debug(args, f"Detected speakers: {detected_speakers}")

    # Detect-only mode
    if args.detect:
        print(f"Detected speakers: {', '.join(sorted(detected_speakers))}")
        return

    # Preview speaker audio mode
    if args.preview_speaker:
        speaker_label = args.preview_speaker
        if speaker_label not in detected_speakers:
            log_error(args, f"Unknown speaker: {speaker_label}")
            print(f"Available speakers: {', '.join(sorted(detected_speakers))}", file=sys.stderr)
            sys.exit(1)

        audio_file = get_audio_file_path(args.input_json)
        if not os.path.exists(audio_file):
            log_error(args, f"Audio file not found: {audio_file}")
            sys.exit(1)

        success = preview_speaker_audio(
            audio_file,
            json_data,
            speaker_label,
            max_samples=args.max_samples,
            args=args
        )
        sys.exit(0 if success else 1)

    # Extract speaker audio mode
    if args.extract_speaker:
        speaker_label = args.extract_speaker
        if speaker_label not in detected_speakers:
            log_error(args, f"Unknown speaker: {speaker_label}")
            print(f"Available speakers: {', '.join(sorted(detected_speakers))}", file=sys.stderr)
            sys.exit(1)

        audio_file = get_audio_file_path(args.input_json)
        if not os.path.exists(audio_file):
            log_error(args, f"Audio file not found: {audio_file}")
            sys.exit(1)

        if args.output:
            output_path = args.output
        else:
            base = get_audio_file_path(args.input_json)
            output_path = f"{base}.speaker_{speaker_label}.mp3"

        if os.path.exists(output_path) and not args.force:
            log_error(args, f"Output file exists: {output_path}")
            log_error(args, "Use -f/--force to overwrite")
            sys.exit(1)

        utterances = get_speaker_utterances(json_data, speaker_label)
        if not utterances:
            log_error(args, f"No utterances found for speaker {speaker_label}")
            sys.exit(1)

        print(f"Extracting audio for speaker {speaker_label}...", file=sys.stderr)
        success, message = extract_speaker_audio(
            audio_file,
            utterances,
            output_path,
            max_samples=args.max_samples,
            args=args
        )

        if success:
            print(f"✓ {message}", file=sys.stderr)
            print(f"Saved to: {output_path}", file=sys.stderr)
            sys.exit(0)
        else:
            log_error(args, message)
            sys.exit(1)

    # Build speaker map
    if args.llm_detect or args.llm_interactive or args.llm_detect_fallback:
        speaker_map = handle_llm_detection(args, json_data, detected_speakers)
    elif args.speaker_map:
        speaker_map = parse_speaker_map_inline(args.speaker_map, detected_speakers)
    elif args.speaker_map_file:
        try:
            speaker_map = parse_speaker_map_file(args.speaker_map_file, detected_speakers)
        except FileNotFoundError:
            log_error(args, f"Mapping file not found: {args.speaker_map_file}")
            sys.exit(1)
    elif args.interactive:
        speaker_map = prompt_interactive_mapping(detected_speakers, args)
    else:
        log_error(args, "No mapping source provided (use -m, -M, --interactive, or --llm-detect)")
        sys.exit(1)

    # Check if user skipped mapping
    if speaker_map is None:
        log_info(args, "Mapping skipped by user - exiting without creating files")
        return

    if not speaker_map:
        log_warning(args, "Empty speaker mapping - no changes will be made")

    # Validate and log mapping
    validate_and_log_mapping(speaker_map, detected_speakers, args)

    # Apply mapping
    log_debug(args, "Applying speaker mapping to JSON...")
    mapped_json = replace_speakers_recursive(json_data, speaker_map)

    # Stdout-only mode
    if args.stdout_only:
        output = {
            "mappings": speaker_map,
            "detected_speakers": sorted(detected_speakers),
        }
        print(json.dumps(output, indent=2))
        return

    # Determine output paths
    if args.output:
        output_base = args.output
    else:
        output_base = generate_output_path(args.input_json, extension='')

    json_output = f"{output_base}.json"
    txt_output = f"{output_base}.txt"

    # Check for existing files
    if not args.force:
        existing = []
        if not args.txt_only and os.path.exists(json_output):
            existing.append(json_output)
        if not args.json_only and os.path.exists(txt_output):
            existing.append(txt_output)

        if existing:
            log_error(args, f"Output file(s) already exist: {', '.join(existing)}")
            log_error(args, "Use -f/--force to overwrite")
            sys.exit(1)

    # Write outputs
    if not args.txt_only:
        write_json(json_output, mapped_json, args)

    if not args.json_only:
        txt_content = generate_txt_from_json(mapped_json, args)
        if txt_content:
            write_txt(txt_output, txt_content, args)
        else:
            log_warning(args, "No transcript segments found in JSON - TXT file not created")

    # Summary
    if not args.quiet:
        outputs = []
        if not args.txt_only:
            outputs.append(json_output)
        if not args.json_only and txt_content:
            outputs.append(txt_output)
        print(f"Created: {', '.join(outputs)}")


if __name__ == "__main__":
    main()