audacity-mcp-server 0.1.17__py3-none-any.whl

audacity_mcp/audacity_client.py

@@ -0,0 +1,347 @@
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+
+from audacity_mcp_shared.constants import PipePaths, Timeouts
+from audacity_mcp_shared.error_codes import AudacityMCPError, ErrorCode
+from audacity_mcp_shared.pipe_protocol import format_command, parse_response
+
+if sys.platform == "win32":
+    import ctypes
+    import ctypes.wintypes
+
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+
+    GENERIC_READ = 0x80000000
+    GENERIC_WRITE = 0x40000000
+    OPEN_EXISTING = 3
+    INVALID_HANDLE_VALUE = ctypes.wintypes.HANDLE(-1).value  # 0xFFFFFFFFFFFFFFFF on 64-bit
+
+    kernel32.CreateFileW.restype = ctypes.wintypes.HANDLE
+    kernel32.CreateFileW.argtypes = [
+        ctypes.wintypes.LPCWSTR,  # lpFileName
+        ctypes.wintypes.DWORD,    # dwDesiredAccess
+        ctypes.wintypes.DWORD,    # dwShareMode
+        ctypes.c_void_p,          # lpSecurityAttributes
+        ctypes.wintypes.DWORD,    # dwCreationDisposition
+        ctypes.wintypes.DWORD,    # dwFlagsAndAttributes
+        ctypes.wintypes.HANDLE,   # hTemplateFile
+    ]
+
+    kernel32.WriteFile.restype = ctypes.wintypes.BOOL
+    kernel32.WriteFile.argtypes = [
+        ctypes.wintypes.HANDLE,            # hFile
+        ctypes.c_void_p,                   # lpBuffer
+        ctypes.wintypes.DWORD,             # nNumberOfBytesToWrite
+        ctypes.POINTER(ctypes.wintypes.DWORD),  # lpNumberOfBytesWritten
+        ctypes.c_void_p,                   # lpOverlapped
+    ]
+
+    kernel32.ReadFile.restype = ctypes.wintypes.BOOL
+    kernel32.ReadFile.argtypes = [
+        ctypes.wintypes.HANDLE,            # hFile
+        ctypes.c_void_p,                   # lpBuffer
+        ctypes.wintypes.DWORD,             # nNumberOfBytesToRead
+        ctypes.POINTER(ctypes.wintypes.DWORD),  # lpNumberOfBytesRead
+        ctypes.c_void_p,                   # lpOverlapped
+    ]
+
+    kernel32.CloseHandle.restype = ctypes.wintypes.BOOL
+    kernel32.CloseHandle.argtypes = [ctypes.wintypes.HANDLE]
+
+    kernel32.WaitNamedPipeW.restype = ctypes.wintypes.BOOL
+    kernel32.WaitNamedPipeW.argtypes = [
+        ctypes.wintypes.LPCWSTR,  # lpNamedPipeName
+        ctypes.wintypes.DWORD,    # nTimeOut (ms)
+    ]
+
+    ERROR_PIPE_BUSY = 231
+
+
+class AudacityClient:
+    def __init__(self):
+        self._lock = asyncio.Lock()
+        self._to_pipe = None
+        self._from_pipe = None
+
+    def _open_pipes(self):
+        try:
+            if sys.platform == "win32":
+                # Audacity requires FromSrvPipe opened first, and both need read+write access
+                self._from_pipe = self._win32_open_pipe(PipePaths.FROM_SRV, GENERIC_READ | GENERIC_WRITE)
+                self._to_pipe = self._win32_open_pipe(PipePaths.TO_SRV, GENERIC_READ | GENERIC_WRITE)
+            else:
+                self._posix_open_pipes()
+        except AudacityMCPError:
+            self._close_pipes()
+            raise
+        except FileNotFoundError:
+            self._close_pipes()
+            raise AudacityMCPError(
+                ErrorCode.PIPE_NOT_FOUND,
+                "Audacity pipe not found. Is Audacity running with mod-script-pipe enabled? "
+                "(Edit > Preferences > Modules > mod-script-pipe = Enabled, then restart Audacity)",
+            )
+        except OSError as e:
+            self._close_pipes()
+            raise AudacityMCPError(ErrorCode.PIPE_OPEN_FAILED, str(e))
+
+    def _posix_open_pipes(self):
+        # Audacity's mod-script-pipe relay opens its WRITE end (FROM) first and
+        # blocks for a reader, so the client must open FROM before TO. The reverse
+        # order (the historical bug) races the relay and yields immediate empty
+        # reads. Open FROM read-only + O_NONBLOCK so it never hangs and reads are
+        # driven by select()/os.read in _posix_send_raw. Open TO with O_NONBLOCK
+        # too (it raises ENXIO until the relay's read end is up — poll briefly),
+        # then clear O_NONBLOCK so os.write to it behaves normally. We deliberately
+        # keep RAW integer fds here (no buffered file object): the relay closes
+        # both ends right after each reply, and a buffered reader's readahead/EOF
+        # handling drops the reply, whereas os.read() returns the bytes reliably.
+        import errno
+        import fcntl
+        import os
+        import time
+
+        to_path, from_path = PipePaths.resolve()
+        from_fd = os.open(from_path, os.O_RDONLY | os.O_NONBLOCK)
+        try:
+            deadline = time.monotonic() + Timeouts.PIPE_OPEN
+            while True:
+                try:
+                    to_fd = os.open(to_path, os.O_WRONLY | os.O_NONBLOCK)
+                    break
+                except OSError as e:
+                    if e.errno == errno.ENXIO and time.monotonic() < deadline:
+                        time.sleep(0.01)
+                        continue
+                    raise
+        except BaseException:
+            os.close(from_fd)
+            raise
+
+        flags = fcntl.fcntl(to_fd, fcntl.F_GETFL)
+        fcntl.fcntl(to_fd, fcntl.F_SETFL, flags & ~os.O_NONBLOCK)
+
+        self._from_pipe = from_fd  # raw int fd (read, non-blocking)
+        self._to_pipe = to_fd      # raw int fd (write, blocking)
+
+    def _win32_open_pipe(self, pipe_path: str, access: int) -> ctypes.wintypes.HANDLE:
+        for _ in range(3):
+            handle = kernel32.CreateFileW(
+                pipe_path,
+                access,
+                0,     # no sharing
+                None,  # default security
+                OPEN_EXISTING,
+                0,     # default attributes
+                None,  # no template
+            )
+            if handle != INVALID_HANDLE_VALUE:
+                return handle
+            err = ctypes.get_last_error()
+            if err == 2:  # ERROR_FILE_NOT_FOUND
+                raise AudacityMCPError(
+                    ErrorCode.PIPE_NOT_FOUND,
+                    "Audacity pipe not found. Is Audacity running with mod-script-pipe enabled? "
+                    "(Edit > Preferences > Modules > mod-script-pipe = Enabled, then restart Audacity)",
+                )
+            if err == ERROR_PIPE_BUSY:
+                # Wait up to 5 seconds for pipe to become available
+                kernel32.WaitNamedPipeW(pipe_path, 5000)
+                continue
+            raise AudacityMCPError(
+                ErrorCode.PIPE_OPEN_FAILED,
+                f"Failed to open pipe {pipe_path}: Win32 error {err}",
+            )
+        raise AudacityMCPError(
+            ErrorCode.PIPE_OPEN_FAILED,
+            f"Pipe {pipe_path} remained busy after retries",
+        )
+
+    def _close_pipes(self):
+        if sys.platform == "win32":
+            for handle in (self._to_pipe, self._from_pipe):
+                if handle is not None:
+                    try:
+                        kernel32.CloseHandle(handle)
+                    except OSError:
+                        pass
+        else:
+            import os
+
+            for fd in (self._to_pipe, self._from_pipe):
+                if fd is not None:
+                    try:
+                        os.close(fd)
+                    except OSError:
+                        pass
+        self._to_pipe = None
+        self._from_pipe = None
+
+    # Audacity's mod-script-pipe relay (Linux) tears down and reopens BOTH FIFO
+    # ends after every command cycle. Even a fresh per-command open races that
+    # reopen, so any single attempt succeeds only ~50% of the time (empty read /
+    # broken pipe), with successes and failures alternating cycle-to-cycle. A
+    # bounded retry — closing our ends between attempts so the relay finishes its
+    # cycle and we reopen clean — makes it reliable. A bad cycle fails fast
+    # (immediate empty read), so the retries are cheap in the common case.
+    _POSIX_SEND_ATTEMPTS = 6
+
+    def _send_raw(self, command_str: str) -> str:
+        if sys.platform == "win32":
+            if self._to_pipe is None or self._from_pipe is None:
+                self._open_pipes()
+            return self._win32_send_raw(command_str)
+
+        import time
+
+        last_raw = ""
+        last_err = None
+        for attempt in range(self._POSIX_SEND_ATTEMPTS):
+            try:
+                self._open_pipes()  # always fresh; never cache a fd across commands
+                raw = self._posix_send_raw(command_str)
+                if "BatchCommand finished" in raw:
+                    return raw  # complete, well-formed response
+                if raw.strip():
+                    last_raw = raw  # non-empty but no terminator: keep as fallback
+            except AudacityMCPError as e:
+                last_err = e
+            finally:
+                self._close_pipes()  # tear our ends down so the relay re-cycles
+            time.sleep(0.05 * (attempt + 1))
+
+        if last_raw:
+            return last_raw
+        raise last_err or AudacityMCPError(
+            ErrorCode.PIPE_READ_FAILED,
+            f"Empty response from Audacity pipe after {self._POSIX_SEND_ATTEMPTS} attempts",
+        )
+
+    def _win32_send_raw(self, command_str: str) -> str:
+        data = command_str.encode("utf-8")
+        bytes_written = ctypes.wintypes.DWORD()
+        try:
+            ok = kernel32.WriteFile(
+                self._to_pipe,
+                data,
+                len(data),
+                ctypes.byref(bytes_written),
+                None,
+            )
+            if not ok:
+                raise OSError(f"WriteFile failed: Win32 error {ctypes.get_last_error()}")
+        except OSError as e:
+            self._close_pipes()
+            raise AudacityMCPError(ErrorCode.PIPE_WRITE_FAILED, str(e))
+
+        try:
+            response_parts = []
+            buf = ctypes.create_string_buffer(65536)
+            while True:
+                bytes_read = ctypes.wintypes.DWORD()
+                ok = kernel32.ReadFile(
+                    self._from_pipe,
+                    buf,
+                    len(buf),
+                    ctypes.byref(bytes_read),
+                    None,
+                )
+                if not ok:
+                    err = ctypes.get_last_error()
+                    raise OSError(f"ReadFile failed: Win32 error {err}")
+                if bytes_read.value == 0:
+                    break
+                chunk = buf.raw[:bytes_read.value].decode("utf-8")
+                response_parts.append(chunk)
+                accumulated = "".join(response_parts)
+                if "\n\n" in accumulated:
+                    break
+            return "".join(response_parts)
+        except OSError as e:
+            self._close_pipes()
+            raise AudacityMCPError(ErrorCode.PIPE_READ_FAILED, str(e))
+
+    def _posix_send_raw(self, command_str: str) -> str:
+        # Operates on the raw int fds from _posix_open_pipes. Closing is left to
+        # the caller (_send_raw's retry loop), which tears the pipes down between
+        # attempts so the relay can complete its cycle.
+        import os
+        import select
+
+        try:
+            os.write(self._to_pipe, command_str.encode("utf-8"))
+        except OSError as e:
+            raise AudacityMCPError(ErrorCode.PIPE_WRITE_FAILED, str(e))
+
+        try:
+            chunks = []
+            while True:
+                # Gate each read so a silent relay can't hang us forever.
+                ready, _, _ = select.select([self._from_pipe], [], [], Timeouts.PIPE_READ)
+                if not ready:
+                    raise AudacityMCPError(
+                        ErrorCode.PIPE_TIMEOUT,
+                        f"Pipe read timed out after {Timeouts.PIPE_READ}s — Audacity may have stopped responding",
+                    )
+                chunk = os.read(self._from_pipe, 65536)
+                if not chunk:  # EOF: relay closed its write end
+                    break
+                chunks.append(chunk)
+                # Audacity terminates every reply with this status line.
+                if b"BatchCommand finished" in b"".join(chunks):
+                    break
+            return b"".join(chunks).decode("utf-8", errors="replace")
+        except AudacityMCPError:
+            raise
+        except OSError as e:
+            raise AudacityMCPError(ErrorCode.PIPE_READ_FAILED, str(e))
+
+    async def execute(self, command: str, extra_params: dict | None = None, **params) -> dict:
+        cmd_str = format_command(command, extra_params=extra_params, **params)
+        async with self._lock:
+            loop = asyncio.get_event_loop()
+            try:
+                raw = await asyncio.wait_for(
+                    loop.run_in_executor(None, self._send_raw, cmd_str),
+                    timeout=Timeouts.COMMAND,
+                )
+            except TimeoutError:
+                self._close_pipes()
+                raise AudacityMCPError(
+                    ErrorCode.PIPE_TIMEOUT,
+                    f"Command timed out after {Timeouts.COMMAND}s: {command}",
+                )
+            except AudacityMCPError:
+                raise
+            except Exception as e:
+                self._close_pipes()
+                raise AudacityMCPError(ErrorCode.COMMAND_FAILED, str(e))
+        return parse_response(raw)
+
+    async def execute_long(self, command: str, extra_params: dict | None = None, **params) -> dict:
+        cmd_str = format_command(command, extra_params=extra_params, **params)
+        async with self._lock:
+            loop = asyncio.get_event_loop()
+            try:
+                raw = await asyncio.wait_for(
+                    loop.run_in_executor(None, self._send_raw, cmd_str),
+                    timeout=Timeouts.LONG_COMMAND,
+                )
+            except TimeoutError:
+                self._close_pipes()
+                raise AudacityMCPError(
+                    ErrorCode.PIPE_TIMEOUT,
+                    f"Long command timed out after {Timeouts.LONG_COMMAND}s: {command}",
+                )
+            except AudacityMCPError:
+                raise
+            except Exception as e:
+                self._close_pipes()
+                raise AudacityMCPError(ErrorCode.COMMAND_FAILED, str(e))
+        return parse_response(raw)
+
+    async def close(self):
+        self._close_pipes()

audacity_mcp/main.py

@@ -0,0 +1,20 @@
+import atexit
+
+from mcp.server.fastmcp import FastMCP
+
+from audacity_mcp.audacity_client import AudacityClient
+from audacity_mcp.tool_registry import register_all_tools
+
+mcp = FastMCP("AudacityMCP")
+client = AudacityClient()
+atexit.register(client.close)
+
+register_all_tools(mcp)
+
+
+def main():
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

audacity_mcp/setup_transcription.py

@@ -0,0 +1,136 @@
+"""Standalone GPU setup/verification helper for local transcription.
+
+Run with `audacity-mcp-setup-gpu` (installed alongside the `audacity-mcp`
+console script). Running it as a console script rather than a loose
+`python script.py` matters: it guarantees the GPU packages get installed
+into, and get tested against, the exact same Python environment that
+`audacity-mcp` itself runs from - installing into the wrong environment
+(a different venv or system Python) is the most common reason GPU setup
+silently doesn't work.
+"""
+import subprocess
+import sys
+
+
+def _detect_nvidia_gpu() -> str | None:
+    """Return the first GPU name from `nvidia-smi`, or None if unavailable.
+
+    No NVIDIA GPU (AMD/Intel graphics, or Apple Silicon/macOS - NVIDIA hasn't
+    shipped macOS drivers in years) means `nvidia-smi` simply won't exist,
+    which this treats the same as "no GPU": CPU transcription, no error.
+    """
+    try:
+        result = subprocess.run(
+            ["nvidia-smi", "--query-gpu=name", "--format=csv,noheader"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except Exception:
+        return None
+    if result.returncode != 0:
+        return None
+    lines = [line.strip() for line in result.stdout.splitlines() if line.strip()]
+    return lines[0] if lines else None
+
+
+def _install_gpu_packages() -> bool:
+    print("Installing nvidia-cublas-cu12 and nvidia-cudnn-cu12...")
+    print(f"  (into {sys.executable})")
+    result = subprocess.run(
+        [sys.executable, "-m", "pip", "install", "nvidia-cublas-cu12", "nvidia-cudnn-cu12"]
+    )
+    return result.returncode == 0
+
+
+def _add_nvidia_dlls_to_path() -> None:
+    """Mirror transcription_tools._setup_cuda_path so this verifies the exact
+    runtime condition the MCP server will hit, not just that pip succeeded.
+
+    Uses __path__, not __file__: nvidia-cublas-cu12/nvidia-cudnn-cu12 are PEP
+    420 namespace packages with no __init__.py, so __file__ is None on
+    current package versions - a package dir (__path__) always exists.
+    """
+    import os
+    for pkg in ("cublas", "cudnn"):
+        try:
+            module = __import__(f"nvidia.{pkg}", fromlist=[pkg])
+            pkg_dir = next(iter(module.__path__), None)
+            if not pkg_dir:
+                continue
+            bin_dir = os.path.join(pkg_dir, "bin")
+            if bin_dir not in os.environ.get("PATH", ""):
+                os.environ["PATH"] = bin_dir + os.pathsep + os.environ.get("PATH", "")
+        except (ImportError, AttributeError, OSError):
+            pass
+
+
+def _verify_gpu_transcription() -> tuple[bool, str]:
+    _add_nvidia_dlls_to_path()
+    try:
+        from faster_whisper import WhisperModel
+    except ImportError:
+        return False, "faster-whisper isn't installed. Run: pip install faster-whisper"
+    try:
+        WhisperModel("tiny", device="cuda", compute_type="float16")
+    except Exception as e:
+        return False, f"{type(e).__name__}: {e}"
+    return True, "GPU transcription is working."
+
+
+def main() -> int:
+    print()
+    print(" ============================================")
+    print("  AudacityMCP - Transcription GPU Setup")
+    print(" ============================================")
+    print()
+    print("Checking for an NVIDIA GPU (nvidia-smi)...")
+    gpu_name = _detect_nvidia_gpu()
+
+    if gpu_name is None:
+        print()
+        print(" No NVIDIA GPU detected.")
+        print()
+        print(" Transcription will use the CPU. That's completely fine for short")
+        print(" clips - just slower for long files (a 3-minute file: ~10s on GPU")
+        print(" vs 4+ minutes on CPU). GPU acceleration ONLY works with NVIDIA GPUs")
+        print(" (AMD/Intel graphics, and Macs, aren't supported by faster-whisper's")
+        print(" backend at all - this isn't something a driver update fixes).")
+        print()
+        print(" If you DO have an NVIDIA GPU: make sure its driver is installed and")
+        print(" that `nvidia-smi` runs successfully in this terminal, then re-run:")
+        print("   audacity-mcp-setup-gpu")
+        print()
+        return 0
+
+    print(f"  Found: {gpu_name}")
+    print()
+
+    if not _install_gpu_packages():
+        print()
+        print(" ERROR: pip install failed - see the error above.")
+        print(" Try running this terminal as administrator, or check your internet connection.")
+        print()
+        return 1
+
+    print()
+    print("Verifying GPU transcription actually works...")
+    ok, message = _verify_gpu_transcription()
+
+    print()
+    if ok:
+        print(f" {message}")
+        print()
+        print(" Done! Restart Claude Desktop (if it's open) - transcription will now use your GPU.")
+        return 0
+    else:
+        print(f" GPU load failed: {message}")
+        print()
+        print(" The packages installed, but faster-whisper couldn't use the GPU.")
+        print(" Common causes: an outdated NVIDIA driver, or a GPU too old for the")
+        print(" compute capability faster-whisper's CTranslate2 backend requires.")
+        print(" AudacityMCP will keep working - it automatically falls back to CPU.")
+        print()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

audacity_mcp/tool_registry.py

@@ -0,0 +1,12 @@
+import importlib
+import pkgutil
+from mcp.server.fastmcp import FastMCP
+
+import audacity_mcp.tools as tools_package
+
+
+def register_all_tools(mcp: FastMCP):
+    for finder, name, ispkg in pkgutil.iter_modules(tools_package.__path__):
+        module = importlib.import_module(f"audacity_mcp.tools.{name}")
+        if hasattr(module, "register"):
+            module.register(mcp)

audacity_mcp/tools/analysis_tools.py

@@ -0,0 +1,86 @@
+import os
+from mcp.server.fastmcp import FastMCP
+from audacity_mcp_shared.error_codes import AudacityMCPError, ErrorCode
+
+
+def register(mcp: FastMCP):
+    from audacity_mcp.main import client
+
+    @mcp.tool()
+    async def analyze_contrast() -> dict:
+        """Analyze the contrast between foreground and background audio. Select a region first.
+        Useful for checking accessibility compliance (WCAG)."""
+        return await client.execute_long("ContrastAnalyser")
+
+    @mcp.tool()
+    async def analyze_find_clipping(duty_cycle_start: int = 3, duty_cycle_end: int = 3) -> dict:
+        """Find clipping in the selected audio and create labels at clipped regions.
+
+        Args:
+            duty_cycle_start: Min number of consecutive clipped samples to detect (1-1000, default 3)
+            duty_cycle_end: Min number of consecutive non-clipped samples to end a region (1-1000, default 3)
+        """
+        if not 1 <= duty_cycle_start <= 1000:
+            raise AudacityMCPError(ErrorCode.VALUE_OUT_OF_RANGE, "duty_cycle_start must be 1-1000")
+        if not 1 <= duty_cycle_end <= 1000:
+            raise AudacityMCPError(ErrorCode.VALUE_OUT_OF_RANGE, "duty_cycle_end must be 1-1000")
+        return await client.execute_long(
+            "FindClipping",
+            DutyCycleStart=duty_cycle_start,
+            DutyCycleEnd=duty_cycle_end,
+        )
+
+    @mcp.tool()
+    async def analyze_plot_spectrum() -> dict:
+        """Open the Plot Spectrum window for the selected audio. Select a region first."""
+        return await client.execute("PlotSpectrum")
+
+    @mcp.tool()
+    async def analyze_beat_finder(thres_val: int = 65) -> dict:
+        """Find beats in the selected audio and add labels at beat positions.
+
+        Args:
+            thres_val: Beat detection threshold (0-100, lower = more sensitive). Default: 65
+        """
+        if not 0 <= thres_val <= 100:
+            raise AudacityMCPError(ErrorCode.VALUE_OUT_OF_RANGE, "Threshold must be 0-100")
+        return await client.execute_long("BeatFinder", thresval=thres_val)
+
+    @mcp.tool()
+    async def analyze_label_sounds(
+        threshold_db: float = -30.0,
+        min_silence_duration: float = 0.5,
+        min_sound_duration: float = 0.1,
+    ) -> dict:
+        """Automatically label regions of sound separated by silence.
+
+        Args:
+            threshold_db: Volume threshold to distinguish sound from silence (dB). Default: -30
+            min_silence_duration: Minimum duration of silence between sounds (seconds). Default: 0.5
+            min_sound_duration: Minimum duration of a sound region (seconds). Default: 0.1
+        """
+        return await client.execute_long(
+            "LabelSounds",
+            Threshold=threshold_db,
+            MinSilence=min_silence_duration,
+            MinSound=min_sound_duration,
+        )
+
+    @mcp.tool()
+    async def analyze_sample_data_export(path: str, limit: int = 100) -> dict:
+        """Export raw sample data from the selected audio to a text file for analysis.
+
+        Args:
+            path: Absolute path for the output file
+            limit: Maximum number of samples to export. Default: 100
+        """
+        if not 1 <= limit <= 1000000:
+            raise AudacityMCPError(ErrorCode.VALUE_OUT_OF_RANGE, "limit must be 1-1000000")
+        from audacity_mcp.tools.project_tools import _safe_path
+        path = _safe_path(path)
+        if os.path.exists(path):
+            raise AudacityMCPError(
+                ErrorCode.INVALID_PATH,
+                f"File already exists: {path}. Use a different filename to avoid overwriting.",
+            )
+        return await client.execute("SampleDataExport", Filename=path, Limit=limit)