dsh-fish-audio

Fish Audio S2.1 plugin for DeepSeek Harness (DSH), Model Context Protocol (MCP) Server, and CLI tool.
Native support for Free Unlimited S2.1-Pro, character voice library search & dynamic switching, singing generation ([singing]), and natural language pitch/emotion modulation.

中文说明文档 (README_CN.md)

✨ Features

• 🆓 Official Unlimited Free Tier: Defaults to s2.1-pro-free, providing high-quality S2.1 neural TTS without token deductions.

• 🎶 Singing & Melody: Instruct the model to sing using inline [singing] tags and melody markers (♪, ~, ——).

• 🎚️ Pitch & Emotion Modulation: Supports open-ended natural language prosody tags:

  • [pitch up] / [high pitch]: Raise vocal pitch (cute / anime voice).

  • [pitch down] / [low pitch]: Lower vocal pitch (deep / authoritative voice).

  • [whispering]: Intimate breathy whisper.

  • [shouting] / [screaming]: Emotional exclamation.

• 🎙️ Rich Voice Library: Search thousands of community and official character voices (e.g. anime characters, singers) by keyword and switch dynamically with persistent memory.

• 🔄 Model & Engine Management: Query and switch between s2.1-pro-free, s2.1-pro, s2-pro, and ASR models.

• 🎧 Speech-to-Text (ASR): High-accuracy audio transcription via transcribe-1 / transcribe-1-pro.

• 🌐 Built-in Proxy Support: Supports HTTP/HTTPS forward proxies (http://127.0.0.1:7892 etc.) using native Node.js HTTP CONNECT tunneling with zero external dependencies.

• 🔌 3-in-1 Architecture:

  1. DeepSeek Harness (Cordis) Native Plugin with GUI Schema settings.

  2. Model Context Protocol (MCP) Stdio Server for Claude Desktop, Antigravity, Cursor, and Cline.

  3. CLI Command-line Tool (fish-audio-mcp / dsh-fish-audio).

Related MCP server: Fish Audio MCP Server

🚀 Quick Start

1. Installation

# Global install for CLI & MCP
npm install -g dsh-fish-audio

# Or inside DeepSeek Harness profile
pnpm add dsh-fish-audio

2. Configure API Key

Set your Fish Audio API key (sk-fish-...) via CLI or environment variable:

# Via CLI (saved to ~/.fish-audio/config.json with 0600 permissions)
fish-audio-mcp apikey sk-fish-xxxxxxxxxxxxxxxxxxxx

# Or via environment variable
export FISH_AUDIO_API_KEY="sk-fish-xxxxxxxxxxxxxxxxxxxx"

🛠️ Usage

Mode A: DeepSeek Harness (Cordis Plugin)

Add dsh-fish-audio to your cordis.patch.yml or configure it via the DeepSeek Harness desktop GUI:

- insert:
    - id: dsh-fish-audio
      name: dsh-fish-audio
      config:
        apiKey: '' # Leave blank to use ~/.fish-audio/config.json or env
        defaultModelId: 568fe6a62f294908936212ce81e201e2 # Default character voice ID
        modelTier: s2.1-pro-free # Default engine model
        outputDir: voice # Relative or absolute audio output directory
        proxyUrl: '' # e.g. http://127.0.0.1:7892 (optional)

Available Agent Tools Registered:

• fish_audio_tts: Synthesize speech or singing into an audio file.

• fish_audio_voices: Search character voice library by keyword.

• fish_audio_set_voice: Switch active character voice ID.

• fish_audio_models: List available official engine models and pricing.

• fish_audio_set_model: Switch active engine model.

• fish_audio_stt: Transcribe audio file or URL to text.

• fish_audio_balance: Query Fish Audio account credits and limits.

Mode B: Model Context Protocol (MCP) Server

Works with Claude Desktop, Antigravity, Cursor, and Cline.

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "fish-audio": {
      "command": "npx",
      "args": ["-y", "dsh-fish-audio", "serve"],
      "env": {
        "FISH_AUDIO_API_KEY": "sk-fish-xxxxxxxxxxxxxxxxxxxx",
        "HTTPS_PROXY": "http://127.0.0.1:7892"
      }
    }
  }
}

Mode C: Command Line Interface (CLI)

# 1. Synthesize Speech
fish-audio-mcp tts "Hello world, this is a test!" -o test.mp3

# 2. Singing Generation
fish-audio-mcp tts "[singing] Happy birthday to you~ Happy birthday to you~ ♪" -o sing.mp3

# 3. Pitch & Prosody Modulation
fish-audio-mcp tts "[pitch up] Look at how high my voice can reach! [whispering] Secret..." -o pitch.mp3

# 4. Search and Switch Voices
fish-audio-mcp voice list "初音未来"
fish-audio-mcp voice set 14d9940607fc477b8115a40b60a29b0b

# 5. List and Switch Underlying Engine Models
fish-audio-mcp model list
fish-audio-mcp model set s2.1-pro-free

# 6. Audio Transcription (STT)
fish-audio-mcp stt ./audio.mp3 --lang zh

# 7. Check Status & Account Balance
fish-audio-mcp status

Mode D: Node.js Programmatic SDK

import { textToSpeech, searchVoices, setActiveVoice } from 'dsh-fish-audio';

// Search voices
const results = await searchVoices('萝莉');

// Generate TTS
const audio = await textToSpeech('[singing] 祝你生日快乐~ ♪', {
  voice: '568fe6a62f294908936212ce81e201e2',
  model: 's2.1-pro-free',
  outputPath: './output.mp3',
});

console.log(`Audio saved to: ${audio.localPath} (${audio.fileSize} bytes)`);

🎵 Singing & Pitch Modulation Guide

Fish Audio S2.1 natively follows descriptive instructions embedded in square brackets [tag]:

Tip for Singing: Combine [singing] with musical symbols like ♪ (melody markers), ~ (vocal vibrato/extension), and —— (sustained notes) to give the neural network clear rhythmic cadence.

📄 License

MIT © Yuki-U