speechhub-cli

Command-line tool for SpeechHub — wraps the TTS, ASR, and Speaker services with profile-based config, human-friendly output, and --json pipe mode.

中文文档 | Command Reference | Changelog

Install

npm install -g speechhub-cli

Verify:

speechhub --version

Quick Start

# 1. Configure your API key and endpoints (interactive)
speechhub configure

# 2. Text-to-speech
speechhub tts synthesize --text "你好，世界" --voice nova --out hello.mp3

# 3. ASR — instant recognition
speechhub asr flash --file audio.wav

# 4. ASR — offline async (long files)
speechhub asr offline --url https://your-storage/audio.wav

# 5. ASR — real-time streaming
speechhub asr stream --file audio.wav

# 6. Speaker diarization
speechhub speaker identify --file meeting.wav

# 7. List available models
speechhub models

Configuration

speechhub-cli stores configuration in ~/.speechhub/config.json.

Interactive setup

speechhub configure               # configure default (test) profile
speechhub configure --profile prod  # configure prod profile

You will be prompted for:

• API Key — your Bella API key
• TTS endpoint — default: https://xapi.ke.com
• ASR endpoint — default: http://voiceflow.ttb.test.ke.com
• Speaker endpoint — default: http://speaker.ttb.test.ke.com

Profile management

speechhub configure list          # list all profiles
speechhub configure use prod      # switch to prod profile

Built-in profiles

| Profile | TTS | ASR | Speaker | |---------|-----|-----|---------| | test (default) | https://xapi.ke.com | http://voiceflow.ttb.test.ke.com | http://speaker.ttb.test.ke.com | | prod | https://xapi.ke.com | https://voiceflow.ke.com | https://speaker.ke.com |

Config file format

~/.speechhub/config.json:

{
  "current": "test",
  "profiles": {
    "test": {
      "api_key": "your-api-key",
      "endpoints": {
        "tts": "https://xapi.ke.com",
        "asr": "http://voiceflow.ttb.test.ke.com",
        "speaker": "http://speaker.ttb.test.ke.com"
      }
    }
  }
}

Environment Variables

Environment variables take priority over profile config.

| Variable | Description | |----------|-------------| | SPEECHHUB_API_KEY | API key (overrides profile) | | SPEECHHUB_TTS_ENDPOINT | TTS service URL | | SPEECHHUB_ASR_ENDPOINT | ASR service URL | | SPEECHHUB_SPEAKER_ENDPOINT | Speaker service URL |

speechhub-cli automatically loads .env from the current directory (or ~/.speechhub/.env as fallback). You can put your credentials in a .env file:

# .env
SPEECHHUB_API_KEY=your-api-key
SPEECHHUB_TTS_ENDPOINT=https://xapi.ke.com
SPEECHHUB_ASR_ENDPOINT=http://voiceflow.ttb.test.ke.com
SPEECHHUB_SPEAKER_ENDPOINT=http://speaker.ttb.test.ke.com

Commands

TTS

speechhub tts synthesize --text "你好" --voice nova --format mp3 --out out.mp3
speechhub tts voices                  # list voices
speechhub tts models                  # list models

ASR

# Flash: synchronous, returns immediately
speechhub asr flash --file audio.wav

# Offline: async, polls until done
speechhub asr offline --url https://your-storage/audio.wav
speechhub asr offline --url https://your-storage/audio.wav --speaker-diarization

# Stream: real-time WebSocket
speechhub asr stream --file audio.wav

# Job management
speechhub asr jobs get <job-id>

Speaker

speechhub speaker identify --file meeting.wav   # diarize + transcribe
speechhub speaker list                           # list registered speakers
speechhub speaker rename <id> "张三" --session <session-id>
speechhub speaker delete <id> --session <session-id>

Models

speechhub models            # show all engines and models
speechhub models tts        # TTS models + voices
speechhub models asr        # ASR engines
speechhub models speaker    # Speaker engines
speechhub models vad        # VAD engines

See Command Reference for complete options for every command.

Pipe Mode

All commands accept --json to emit machine-readable output on stdout (errors go to stderr):

# Extract transcript text
speechhub asr flash --file audio.wav --json | jq '.flash_result.sentences[].text'

# Get speaker list as JSON
speechhub speaker list --json | jq '.[].name'

# Stream events line-by-line (NDJSON)
speechhub speaker identify --file meeting.wav --json | grep '"type":"utterance"'

Per-command Endpoint Override

Use --endpoint to temporarily override the service endpoint for a single command without editing the profile:

speechhub asr flash --file a.wav --endpoint http://192.168.1.10:8080
speechhub tts synthesize --text "hi" --endpoint http://localhost:3000

Troubleshooting

API key not configured Run speechhub configure and enter your API key.

Profile "prod" not found Run speechhub configure --profile prod to create it first.

HTTP 401 / UNAUTHORIZED Your API key is invalid or expired. Check SPEECHHUB_API_KEY or re-run speechhub configure.

ECONNREFUSED / Network error The service endpoint is not reachable. Check speechhub configure list to confirm your endpoint URLs, or use --endpoint to override for a single command.

POLL_TIMEOUT The offline ASR job did not complete within the timeout. Increase it with --timeout 600, or query manually with speechhub asr jobs get <job-id>.

Verbose output for debugging Use --verbose to print the raw HTTP request and response:

speechhub asr flash --file audio.wav --verbose

Getting Help

• GitHub Issues: report bugs or feature requests
• speechhub --help — top-level help
• speechhub <command> --help — command-level help