modules/audio_input.py

"""Audio input capture module — stub implementation.

.. warning::
    This module is a stub. Audio capture is not yet implemented.
    ``render_audio_panel()`` returns ``(None, None)`` and emits an explicit
    warning so the caller knows it is using placeholder data.

Full implementation will add:
    - Microphone capture via sounddevice
    - Real-time RMS / spectral analysis
    - WAV file export for prompt steering
"""

from __future__ import annotations

import warnings
from pathlib import Path
from typing import Optional, Tuple


def render_audio_panel(
    *,
    key_prefix: str = "audio",
    output_dir: Optional[str] = None,
) -> Tuple[Optional[str], Optional[dict]]:
    """Render an audio input panel in the Streamlit UI.

    .. warning::
        **STUB** — audio_input not yet implemented.
        Returns ``(None, None)`` and uses default audio context for steering.

    Parameters
    ----------
    key_prefix : str
        Streamlit widget key prefix (for state isolation).
    output_dir : str, optional
        Directory to save captured audio clips.

    Returns
    -------
    tuple[str | None, dict | None]
        ``(audio_file_path, analysis_dict)`` — both are ``None`` in this stub.
    """
    warnings.warn(
        "audio_input not yet implemented — using default audio context for steering. "
        "Implement modules/audio_input.py for real microphone capture.",
        UserWarning,
        stacklevel=2,
    )

    try:
        import streamlit as st
        st.info(
            "🎙️ **Audio Input**: Microphone capture not yet implemented. "
            "Using default audio context.",
            icon="ℹ️",
        )
    except ImportError:
        pass

    return None, None