Voice dictation

기준일: 2026-07-26
공식 기준: Voice dictation

Voice dictation 문서는 Claude Code 공식 문서(voice-dictation)를 한국어로 정리한 가이드입니다. Speak your prompts in the Claude Code CLI with hold-to-record or tap-to-record voice dictation. 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치 버전과 공식 원문을 확인하세요.

핵심 요약

Speak your prompts in the Claude Code CLI with hold-to-record or tap-to-record voice dictation.

한국어 가이드 범위: voice-dictation 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Voice dictation
• 요구사항
• Enable voice dictation
• Hold to record
• Tap to record and send
• Change the dictation language
• Rebind the dictation key
• 트러블슈팅
• Terminal not listed in macOS Microphone settings
• 함께 보기

상세 내용

Voice dictation

Speak your prompts in the Claude Code CLI with hold-to-record or tap-to-record voice dictation.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

요구사항

Voice dictation streams your recorded audio to Anthropic's servers for transcription. Audio is not processed locally. It needs all of the following:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• A Claude.ai account: the speech-to-text service is only available when you authenticate with one, and is not available when Claude Code is configured to use an Anthropic API key directly, Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry.
• An organization without HIPAA compliance enabled: /voice shows Voice mode is disabled by your organization's policy when this restriction applies.
• A local microphone: voice dictation does not work in remote environments such as Claude Code on the web or SSH sessions.
• WSLg, if you run Claude Code in WSL: WSLg is included with WSL2 when installed from the Microsoft Store on Windows 10 or 11. If WSLg is not available, for example on WSL1, run Claude Code in native Windows instead.

Enable voice dictation

Run /voice to enable dictation. The first time you enable it, Claude Code runs a microphone check. On macOS, this triggers the system microphone permission prompt for your terminal if it has never been granted.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Command	Effect
/voice	Toggle on or off, keep the current mode
/voice hold	Enable in hold mode
/voice tap	Enable in tap mode
/voice off	Disable

/voice
Voice mode enabled (hold). Hold space to record. Dictation language: en (/config to change).

Hold to record

Hold mode is push-to-talk: recording runs while you hold the key and stops when you release it. This is the default mode.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

> refactor the auth middleware to ▮
  # hold space, speak "use the new token validation helper"
> refactor the auth middleware to use the new token validation helper▮

Tap to record and send

Tap mode toggles recording with a single keypress: tap once to start, speak, then tap again to send the prompt. There is no warmup, and you don't need to keep the key held.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Change the dictation language

Voice dictation uses the same language setting that controls Claude's response language. If that setting is empty, dictation defaults to English. In the VS Code extension, if language is empty, dictation uses VS Code's accessibility.voice.speechLanguage setting before defaulting to English.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Rebind the dictation key

The dictation key is bound to voice:pushToTalk in the Chat context and defaults to Space. The same binding controls both hold and tap modes. Rebind it in ~/.claude/keybindings.json:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

트러블슈팅

Common issues when voice dictation does not activate or record:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• Voice mode requires a Claude.ai account: you are authenticated with an API key or a third-party provider. Run /login to sign in with a Claude.ai account.
• Voice mode is disabled by your organization's policy: your organization's compliance configuration disables voice dictation, as described in Requirements. Contact your organization administrator to confirm whether voice dictation is available for your organization.
• Microphone access is denied: grant microphone permission to your terminal in system settings. On macOS, go to System Settings → Privacy & Security → Microphone and enable your terminal app, then run /voice again. On Windows, go to Settings → Privacy & security → Microphone and turn on microphone access for desktop apps, then run /voice again. If your terminal isn't listed in the macOS settings, see Terminal not listed in macOS Microphone settings.
• No audio recording tool found on Linux: the native audio module could not load and no fallback is installed. Install SoX with the command shown in the error message, for example sudo apt-get install sox.
• Voice mode requires a microphone, but SoX could not open an audio capture device: SoX is installed, but the host has no audio capture device, for example a headless server or a container. Run Claude Code on a machine with a microphone. {/* min-version: 2.1.195 */}As of v2.1.195, Claude Code on Linux reports this message in that situation; earlier versions asked you to install SoX even when it was already installed.
• Voice mode could not find a working audio recorder in WSL: WSLg routes audio through PulseAudio rather than an ALSA device, so SoX needs its PulseAudio backend installed explicitly. Run sudo apt install sox libsox-fmt-pulse. Installing sox alone pulls in the ALSA backend, which cannot record on WSL because there is no /dev/snd device.
• Voice input is failing repeatedly and has been paused: voice dictation hit several capture failures in a row and stopped attempting new sessions until one succeeds. A failure counts whether the microphone fails to start or the recorder starts and then stops without producing any audio. This usually means the microphone or audio stack on this host can't capture audio, for example a headless server, a remote shell with no audio passthrough, or a denied microphone permission. Confirm a working input device, fix the underlying cause from the entries above, then trigger voice again. {/* min-version: 2.1.202 */}Before v2.1.202, only start-up failures counted toward the pause.
• Nothing happens when holding Space in hold mode: watch the prompt input while you hold. If spaces keep accumulating, voice dictation is likely off; run /voice hold to enable it. If only one or two spaces appear and then nothing, voice dictation is on but hold detection is not triggering. Hold detection requires your terminal to send key-repeat events, so it can't detect a held key if key-repeat is disabled at the OS level. Switch to tap mode with /voice tap to avoid the key-repeat requirement.
• Tapping Space types a space instead of recording in tap mode: the first tap only starts recording when the prompt input is empty. Clear the input first, or check that you are in tap mode by running /voice tap.
• No audio detected from microphone: recording started but captured silence. Confirm the correct input device is set as the system default and that its input level is not muted or near zero. On Windows, open Settings → System → Sound → Input and select your microphone. On macOS, open System Settings → Sound → Input.
• Voice connection failed: your recording never reached the transcription service because the connection failed. Check your network and try again. {/* min-version: 2.1.200 */}A recording that captures no audio reports No audio detected from microphone instead of this message. Before v2.1.200, a silent microphone could report a connection failure, which suggested a network problem when the actual issue was the input device.
• No speech detected: audio reached the transcription service but no words were recognized. Speak closer to the microphone, reduce background noise, and confirm your dictation language matches the language you are speaking.
• Transcription is garbled or in the wrong language: dictation defaults to English. If you are dictating in another language, set it in /config first. See Change the dictation language.

Terminal not listed in macOS Microphone settings

If your terminal app does not appear under System Settings → Privacy & Security → Microphone, there is no toggle you can enable. Reset the permission state for your terminal so the next /voice run triggers a fresh macOS permission prompt.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

함께 보기

주요 항목:

• Customize keyboard shortcuts: rebind voice:pushToTalk and other CLI keyboard actions
• Configure settings: full reference for voice, language, and other settings keys
• Interactive mode: keyboard shortcuts, input modes, and session controls
• Commands: reference for /voice, /config, and all other commands

실습 체크리스트

1. 공식 문서와 로컬/SDK 버전을 대조합니다.
2. 관련 CLI·SDK 옵션은 공식 페이지와 --help로 교차 확인합니다.
3. Agent SDK 예시는 TypeScript/Python 패키지 최신 API를 우선합니다.
4. 권한·호스팅·보안 설정 변경 후 통합 테스트를 실행합니다.

자주 쓰는 명령·설정 예시

/voice
Voice mode enabled (hold). Hold space to record. Dictation language: en (/config to change).

While voice dictation is enabled, the input footer shows a `hold space to speak` hint when the prompt is empty. The hint reflects your current `voice:pushToTalk` binding and updates if you [rebind the dictation key](#rebind-the-dictation-key). The hint text is the same in both modes, and it does not appear if you have a [custom status line](/docs/en/statusline) configured.

Transcription is tuned for coding vocabulary in both modes. Common development terms like `regex`, `OAuth`, `JSON`, and `localhost` are recognized correctly, and your current project name and git branch name are added as recognition hints automatically.

## Hold to record

Hold mode is push-to-talk: recording runs while you hold the key and stops when you release it. This is the default mode.

Hold `Space` to start recording. Claude Code detects a held key by watching for rapid key-repeat events from your terminal, so there is a brief warmup before recording begins. The footer shows `keep holding…` during warmup, then switches to a live waveform once recording is active.

The first couple of key-repeat characters type into the input during warmup and are removed automatically when recording activates. A single `Space` tap still types a space, since hold detection only triggers on rapid repeat.

  To skip the warmup, switch to [tap mode](#tap-to-record-and-send) with `/voice tap`, or [rebind to a modifier combination](#rebind-the-dictation-key) like `meta+k`. Modifier combos start recording on the first keypress.

Your speech appears in the prompt as you speak, dimmed until the transcript is finalized. Release `Space` to stop recording and finalize the text. The transcript is inserted at your cursor position and the cursor stays at the end of the inserted text, so you can mix typing and dictation in any order. Hold `Space` again to append another recording, or move the cursor first to insert speech elsewhere in the prompt:

By default, releasing the key inserts the transcript and waits for you to press `Enter`. Set `"autoSubmit": true` in the `voice` settings object to send the prompt automatically when you release the key, as long as the transcript is at least three words long.

## Tap to record and send

Tap mode toggles recording with a single keypress: tap once to start, speak, then tap again to send the prompt. There is no warmup, and you don't need to keep the key held.

Enable tap mode with `/voice tap`. With the prompt input empty, tap `Space` to start recording. The footer shows a live waveform while recording. Tap `Space` again to stop.

Claude Code inserts the transcript and submits the prompt automatically when the transcript is at least three words long. Shorter transcripts are inserted but not submitted, so an accidental tap does not send a stray word.

The three-word threshold counts words for languages written without spaces. As of v2.1.195, Japanese, Chinese, and Thai transcripts count individual words, so they auto-submit in tap mode and in hold mode with `autoSubmit`. Earlier versions counted a transcript with no spaces as one word and never submitted it automatically.

The first tap only starts recording when the prompt input is empty, so you can still type spaces normally while composing a message. The second tap stops recording regardless of input contents. Recording also stops automatically after 15 seconds of silence or two minutes total.

## Change the dictation language

Voice dictation uses the same [`language` setting](/docs/en/settings) that controls Claude's response language. If that setting is empty, dictation defaults to English. In the VS Code extension, if `language` is empty, dictation uses VS Code's `accessibility.voice.speechLanguage` setting before defaulting to English.

  | Language   | Code |
  | :--------- | :--- |
  | Czech      | `cs` |
  | Danish     | `da` |
  | Dutch      | `nl` |
  | English    | `en` |
  | French     | `fr` |
  | German     | `de` |
  | Greek      | `el` |
  | Hindi      | `hi` |
  | Indonesian | `id` |
  | Italian    | `it` |
  | Japanese   | `ja` |
  | Korean     | `ko` |
  | Norwegian  | `no` |
  | Polish     | `pl` |
  | Portuguese | `pt` |
  | Russian    | `ru` |
  | Spanish    | `es` |
  | Swedish    | `sv` |
  | Turkish    | `tr` |
  | Ukrainian  | `uk` |

Set the language in `/config` or directly in settings. You can use either the [BCP 47 language code](https://en.wikipedia.org/wiki/IETF_language_tag) or the language name:

If your `language` setting is not in the supported list, `/voice` warns you on enable and falls back to English for dictation. Claude's text responses are not affected by this fallback.

## Rebind the dictation key

The dictation key is bound to `voice:pushToTalk` in the `Chat` context and defaults to `Space`. The same binding controls both hold and tap modes. Rebind it in [`~/.claude/keybindings.json`](/docs/en/keybindings):

관련 링크

• 공식 원문: voice-dictation
• 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·API 이름은 설치 버전에 따라 달라질 수 있습니다.