AuralWise CLI

中文文档

Command-line interface for AuralWise Speech Intelligence API.

One API call returns transcription, speaker diarization, speaker embeddings, word-level timestamps, and 521-class audio event detection — all at once.

Features

• Speech Transcription — 99 languages, with two tiers controlled by optimize: an optimize tier (faster & cheaper, segment-level timestamps) for zh/en/es/fr/pt, and a standard tier (highest quality, word-level timestamps) for all languages. By default the server auto-selects the tier by detected language
• Speaker Diarization — Automatic speaker count detection, per-segment speaker labels
• Speaker Embeddings — 192-dim voice print vectors for cross-recording speaker matching
• Timestamps — Word-level (~10ms) or segment-level (~100ms) precision
• Audio Event Detection — 521 AudioSet sound event classes (applause, cough, music, keyboard, etc.)
• VAD — Voice Activity Detection segments
• Batch Mode — Half-price processing using off-peak GPU capacity, delivered within 24h
• Local Transcoding + Vocal Enhancement — Automatically transcodes audio to mono 16kHz 32kbps MP3 and applies a vocal enhancement filter chain (denoise, highpass, EQ, loudness normalization) before upload, cutting upload size dramatically and improving ASR accuracy on noisy recordings
• Account & Rate-limit Aware — account command surfaces balance, tier limits, and usage; automatic Retry-After backoff on rate-limit (429), with optional client-side request pacing

Installation

npm install -g auralwise_cli

Requires Node.js >= 18.

Quick Start

# Set your API key (get one at https://auralwise.cn)
export AURALWISE_API_KEY=asr_xxxxxxxxxxxxxxxxxxxx

# Transcribe from URL — waits for completion and prints results
auralwise transcribe https://example.com/meeting.mp3

# Transcribe a local file (auto base64 upload)
auralwise transcribe ./recording.wav

# By default the server picks the tier by language. Force the optimize tier
# (faster, cheaper, segment-level timestamps) explicitly:
auralwise transcribe ./meeting.mp3 --optimize --language zh

# Force the standard tier (highest quality, word-level timestamps):
auralwise transcribe ./interview.mp3 --standard

# Submit without waiting
auralwise transcribe https://example.com/audio.mp3 --no-wait

# Get JSON output
auralwise transcribe ./audio.mp3 --json --output result.json

Commands

auralwise transcribe <source>

Submit an audio file for processing. <source> can be an HTTP(S) URL or a local file path.

Input modes:

• URL mode — Pass an https://... URL. By default the CLI downloads and transcodes the audio locally before upload; if ffmpeg is missing or transcoding is disabled, the URL is submitted directly to the API.
• File mode — Pass a local file path; the CLI reads, transcodes, and uploads as base64.

Local transcoding pipeline (default ON):

When ffmpeg is available on your PATH, the CLI first converts your audio to mono 16kHz 32kbps MP3 with a vocal enhancement filter chain (afftdn denoise → 80Hz highpass → two-band EQ → dynaudnorm loudness). This typically shrinks uploads by 10-20× and yields cleaner ASR on noisy recordings. Temp files are deleted immediately after the upload succeeds.

• If ffmpeg isn't installed, the CLI prints a one-time warning and submits the original file/URL unchanged.
• If the filter chain is incompatible with a particular source, it falls back to a plain transcode (same format, no filters).
• Upload size is capped at 150 MB. A local file exceeding the limit aborts with an error; a URL source that exceeds the limit after transcoding falls back to submitting the URL directly.
• Pass --no-transcode to skip transcoding entirely and upload the file as-is.

Upstream service limits (validated locally before upload):

| Limit | Value | Notes | |-------|-------|-------| | Minimum file size | 1 KB | Anything smaller is rejected as not a valid audio file | | Maximum file size | 2 GB | Upstream hard cap | | Maximum duration | 5 hours | Probed via ffprobe when available; otherwise enforced server-side |

Common options:

| Option | Description | |--------|-------------| | --language <lang> | ASR language code (zh, en, ja, ...) or auto-detect if omitted | | --optimize | Force optimize tier (faster, cheaper, segment-level timestamps; zh/en/es/fr/pt) | | --standard | Force standard tier (highest quality, word-level timestamps, all languages) | | --no-asr | Disable transcription | | --no-diarize | Disable speaker diarization | | --no-events | Disable audio event detection | | --no-transcode | Skip local transcoding; upload the original file as-is | | --hotwords <words> | Boost recognition of specific words (comma-separated) | | --num-speakers <n> | Set fixed number of speakers | | --max-speakers <n> | Max speakers for auto-detection (default: 10) | | --batch | Use batch mode (half-price, 24h delivery) | | --no-wait | Return immediately after task creation | | --json | Output result as JSON | | --output <file> | Save result to file | | --callback-url <url> | Webhook URL for completion notification |

Advanced ASR options:

| Option | Description | |--------|-------------| | --beam-size <n> | Beam search width (default: 5) | | --best-of <n> | Best-of sampling count, 1-20 (only when --temperature > 0) | | --temperature <n> | Decoding temperature (default: 0.0) | | --initial-prompt <text> | Guide transcription style | | --timestamp-level <level> | word or segment (optimize tier only; experimental) | | --vad-threshold <n> | VAD sensitivity 0-1 (default: 0.35) | | --vad-speech-pad <ms> | Speech segment padding in ms (default: 30) | | --diarize-min-segment <s> | Min segment duration (sec) for embedding extraction (default: 0.5) | | --diarize-single-speaker-threshold <n> | Single-speaker detection threshold (default: 0.05) | | --events-threshold <n> | Audio event confidence threshold (default: 0.3) | | --events-classes <list> | Only detect specific event classes |

auralwise tasks

List your tasks with optional filtering.

auralwise tasks                          # List all tasks
auralwise tasks --status done            # Only completed tasks
auralwise tasks --page 2 --page-size 50  # Pagination
auralwise tasks --json                   # JSON output

auralwise task <id>

Get details of a specific task.

auralwise task 550e8400-e29b-41d4-a716-446655440000
auralwise task 550e8400-e29b-41d4-a716-446655440000 --json

auralwise result <id>

Retrieve the full result of a completed task.

auralwise result <task-id>                     # Pretty-printed output
auralwise result <task-id> --json              # JSON output
auralwise result <task-id> --output result.json  # Save to file

auralwise delete <id>

Delete a task and its associated files.

auralwise delete <task-id>           # With confirmation prompt
auralwise delete <task-id> --force   # Skip confirmation

auralwise events

Browse the 521 AudioSet sound event classes.

auralwise events                       # List all 521 classes
auralwise events --search Cough        # Search by name
auralwise events --category Music      # Filter by category
auralwise events --json                # JSON output

auralwise account

Show your account balance, effective limits, and current usage — read this before batch-submitting to pace yourself and avoid 402/429.

auralwise account          # Pretty-printed
auralwise account --json   # Raw JSON

Account

  Available: ¥1001.70
  Balance: ¥999.00
  Held: ¥0.00
  Resource pack: ¥2.70
  Tier: 3
  Concurrency: 0 active / 11 limit (11 available)
  Batch in progress: 0
  Rate limit: 11 req/s (burst 11)

| Field | Meaning | |-------|---------| | available_balance | Actual gate for submitting tasks = balance + resource_pack − held_amount. Below the task cost → 402. | | held_amount | Funds frozen by in-flight tasks (released on completion/failure). | | concurrency_limit / available_concurrency | Max simultaneous non-batch tasks, and how many you can still submit now. 0 → 429 concurrency_limit_exceeded. | | tps_limit / tps_burst | Request rate cap (req/s) and burst capacity, shared across all /v1 requests. Over the cap → 429 rate_limited. | | waiting_batch_tasks | Batch tasks in progress (batch is exempt from the concurrency limit). |

Rate limits & automatic retries

The API enforces two independent limits, both scaled by account tier (see auralwise account):

• Request rate (TPS) — a per-account token bucket over all /v1 requests. Exceeding it returns 429 rate_limited with a Retry-After header.
• Concurrency — max simultaneous non-batch tasks, checked only when submitting. Exceeding it returns 429 concurrency_limit_exceeded (batch tasks are exempt).

The CLI handles these for you:

• Automatic backoff on rate_limited — honors the server's Retry-After, then exponential backoff with jitter, up to --max-retries times (default 5). Safe because a rate-limited request is rejected before creating anything.
• Clear, actionable errors — 402 (recharge / wait), 429 concurrency_limit_exceeded (wait for slots or use --batch), and exhausted rate_limited retries are surfaced with a hint instead of being retried blindly.
• Optional client-side pacing — pass --tps <n> (and --burst <n>) to proactively cap outgoing requests to your account's tps_limit, smoothing bursts before they hit the server.

Configuration

API Key

Set your API key via --api-key flag or environment variable:

# Environment variable (recommended)
export AURALWISE_API_KEY=asr_xxxxxxxxxxxxxxxxxxxx

# Or pass directly
auralwise --api-key asr_xxxx transcribe ./audio.mp3

Base URL

Override the API endpoint (default: https://api.auralwise.cn/v1):

auralwise --base-url https://your-private-instance.com/v1 transcribe ./audio.mp3

Language

The CLI supports English and Chinese interfaces:

auralwise --locale zh --help           # Chinese interface
auralwise --locale en transcribe --help  # English interface (default)

Rate limiting (global flags)

| Flag | Description | |------|-------------| | --tps <n> | Client-side request rate cap in req/s (match your account tps_limit; 0 = off, default) | | --burst <n> | Burst capacity for --tps pacing (default: 5) | | --max-retries <n> | Max automatic retries on 429 rate_limited before giving up (default: 5) |

# Proactively pace to a tier-3 account's limit (11 req/s) during a busy loop
auralwise --tps 11 --burst 11 tasks --page-size 50

Examples

Meeting transcription with speaker diarization

auralwise transcribe ./meeting.mp3 \
  --optimize \
  --language zh \
  --max-speakers 5 \
  --output meeting_result.json

Batch processing (half-price)

# Submit in batch mode — processed during off-peak hours, 50% discount
auralwise transcribe https://storage.example.com/archive.mp3 \
  --batch \
  --no-wait \
  --callback-url https://your-server.com/webhook

Audio event detection only

auralwise transcribe ./audio.mp3 \
  --no-asr \
  --no-diarize \
  --events-classes "Cough,Music,Applause" \
  --json

Transcription only (no diarization, no events)

auralwise transcribe ./podcast.mp3 \
  --no-diarize \
  --no-events \
  --hotwords "AuralWise,PGPU" \
  --output transcript.json

Output Format

Pretty-printed (default)

Audio Duration: 5.3min
Language: zh (99%)
Speakers: 2

Transcription

[0:00.5 - 0:02.3] SPEAKER_0: This is the first sentence
[0:02.5 - 0:04.1] SPEAKER_1: And this is the reply

Audio Events

[0:45.0 - 0:45.9] Cough (87%)
[1:20.0 - 1:25.0] Music (92%)

Speaker Embeddings

  SPEAKER_0: 25 segments, 192-dim vector
  SPEAKER_1: 18 segments, 192-dim vector

JSON (--json)

Returns the full API response. See API documentation for the complete schema.

Transcription tiers

Two tiers are selected via optimize (the legacy --optimize-zh flag is a deprecated alias for --optimize):

| | Optimize tier (--optimize) | Standard tier (--standard) | |---|---|---| | Languages | zh, en, es, fr, pt | All languages | | Timestamps | Segment-level (start/end, no words) | Word-level (words[]) | | Strengths | Faster, cheaper | Highest quality, hotwords, code-switching | | Billing | zh_lite rate | standard rate |

Default (no flag): the server auto-selects by detected language — zh/en/es/fr/pt use the optimize tier, others fall back to standard. Non-eligible languages always run on the standard tier even with --optimize. Pass --standard to force word-level timestamps on every language.

Pricing

| Capability | Standard | Batch (50% off) | |-----------|----------|-----------------| | Optimize tier (zh/en/es/fr/pt) | ¥0.27/hr | ¥0.14/hr | | Standard tier (all languages, word timestamps) | ¥1.20/hr | ¥0.60/hr | | Speaker diarization (labels + embeddings) | +¥0.40/hr | +¥0.20/hr | | Audio event detection (521 classes) | +¥0.10/hr | +¥0.05/hr |

Example: 100 hours of Chinese meetings (full features) = ¥39 in batch mode.

API Documentation

Full API reference: https://auralwise.cn/api-docs

License

MIT