Audio Playback

Provides a dedicated MCP server to start, stop, and inspect playback of local audio files via a configurable virtual output device.

python

GitHub Stars

python

Language

6 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "dcarter610-mcp-virtual-audio-player": {
      "command": "python",
      "args": [
        "-m",
        "audio_playback_server"
      ],
      "env": {
        "FFPLAY_PATH": "ffplay",
        "AUDIO_ROOT_DIR": "<path to root audio directory>",
        "DEFAULT_FORMAT": "wav",
        "AUDIO_OUTPUT_DEVICE": "<virtual output device>",
        "AUDIO_PLAYBACK_CONFIG": "<path to config json>"
      }
    }
  }
}

You run a lightweight MCP server that exposes a single audio_playback tool to control local audio playback through a configurable virtual audio output. It lets you start, stop, and inspect playback, while keeping file access constrained to a designated root directory for safety and predictability.

How to use

Interact with the audio_playback tool through your MCP client to manage playback of local audio files. You can start playing a file, stop the current playback, or query the current status including a position estimate. When you request a play action, you specify a file relative to your configured audio root directory. The server enforces path safety to prevent accessing files outside the root.

Practical usage patterns include starting playback of a chosen file, optionally looping, and later stopping it to free up resources. You can also query the current status to monitor where you are in the track, including which file is playing and how far into it you are.

How to install

Prerequisites you need before installing and running this server:

Python 3.8+ (recommended) is installed on your system.
A Python virtual environment tool is available (venv on most systems).

Step by step commands you should run in your project directory:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Additional content

Configuration is provided via environment variables and an optional JSON config file. Environment variables take precedence over JSON values. The key settings are:

AUDIO_ROOT_DIR: Root directory containing allowed audio files.
AUDIO_OUTPUT_DEVICE: Identifier for the virtual audio output device. Optional:
DEFAULT_FORMAT: File extension to append when none is provided (default is wav).
FFPLAY_PATH: Path to the ffplay binary (default is ffplay).
AUDIO_PLAYBACK_CONFIG: Path to a JSON file with any of the above keys.

To start the server in stdio mode, set the required environment variables and run the Python module responsible for the server:

AUDIO_ROOT_DIR=/path/to/audio \
AUDIO_OUTPUT_DEVICE="Virtual Cable" \
python -m audio_playback_server

Available tools

audio_playback

Controls playback of local audio files with actions: play a file, stop, and query status with a position estimate. The tool enforces that playback is started from a file under AUDIO_ROOT_DIR and can report the current status including the playing file and position.

Built by

VeilStrat

AI signals for GTM teams