<img src="https://raw.githubusercontent.com/AssemblyAI/assemblyai-node-sdk/main/assemblyai.png" width="500"/>
npm
Test
GitHub License
AssemblyAI Twitter
Discord
AssemblyAI JavaScript SDK
The AssemblyAI JavaScript SDK는 비동기(async) 및 스트리밍 전사(streaming transcription), 그리고 텍스트-음성 변환(text-to-speech)을 지원하는 AssemblyAI API와 상호 작용할 수 있는 사용하기 쉬운 인터페이스를 제공합니다. 이 SDK는 주로 TypeScript로 작성되었으며 모든 타입이 내보내지되, 다른 런타임과도 호환됩니다.
Claude Code
이 저장소에는 CLAUDE.md 파일이 포함되어 있으며, 이 파일은 Claude Code에게 해당 SDK에 대한 컨텍스트(핵심 API, 일반적인 패턴 및 주의사항)를 제공합니다. Claude Code에서 이 저장소를 열면, 더 나은 도움을 주기 위해 자동으로 이 파일을 읽습니다.
AI 코딩 에이전트와 함께 사용하기
만약 이 SDK를 Claude Code, Cursor, Copilot 또는 다른 AI 코딩 어시스턴트와 통합하는 경우, 에이전트가 오래된 모델 이름이나 매개변수에 기반하여 코드를 생성하지 않도록 현재 API 컨텍스트를 제공해야 합니다.
가장 효과적인 방법은 프로젝트 지침을 사용하는 것입니다. 다음 내용을 CLAUDE.md, .cursorrules, AGENTS.md 또는 이에 상응하는 에이전트 지침 파일에 추가하십시오:
AssemblyAI 코드를 작성하기 전에 항상 https://assemblyai.com/docs/llms.txt를 가져오십시오. API가 변경되었으므로 암기된 매개변수 이름에 의존하지 마십시오.
세션 중 온디맨드(on-demand) 문서 조회를 위해 AssemblyAI docs MCP 서버를 연결하십시오:
claude mcp add assemblyai-docs --transport http https://www.assemblyai.com/docs/mcp
깊은 SDK 컨텍스트를 위해 AssemblyAI skill을 설치하십시오. 이는 Claude Code, Cursor, Codex 및 기타 에이전트와 작동합니다:
npx skills add AssemblyAI/assemblyai-skill
에이전트가 코드를 작성하는 대신 오디오를 전사(transcribe)하거나 요약하도록 하려면, AssemblyAI 계정에서 작업을 실행하는 [AssemblyAI MCP 서버]를 연결하세요:
claude mcp add --transport http assemblyai https://mcp.assemblyai.com/mcp
Cursor 설정 방법, MCP 도구 세부 정보 및 최적의 결과를 위한 팁은 [코딩 에이전트 프롬프트(Coding agent prompts)]를 참조하세요.
문서 (Documentation)
단계별 지침과 저희 AI 모델 및 API에 대한 더 많은 세부 정보를 얻으려면 [AssemblyAI 문서]를 방문하세요.
SDK 유형, 함수 및 클래스에 대한 자세한 내용은 [SDK API 레퍼런스]를 탐색해 보세요.
빠른 시작 (Quickstart)
선호하는 패키지 관리자를 사용하여 AssemblyAI SDK를 설치하세요:
그런 다음, assemblyai 모듈을 가져와 API 키로 AssemblyAI 객체를 생성하세요:
import { AssemblyAI } from "assemblyai";
const baseUrl = "https://api.assemblyai.com";
...
이제 client 객체를 사용하여 AssemblyAI API와 상호 작용할 수 있습니다.
CDN 사용하기 (Using a CDN)
[UNPKG]와 같은 자동 CDN을 사용하여 스크립트 태그에서 라이브러리를 로드할 수 있습니다.
:version을 원하는 버전 또는 latest로 대체하세요.- 비축소(non-minified) 버전을 로드하려면
.min을 제거하세요.
- 전체 SDK를 로드하려면
.streaming을 제거하세요. 스트리밍 STT 전용 버전을 로드하려면 .streaming을 유지하세요.
<script src="https://www.unpkg.com/assemblyai@:version/dist/assemblyai.umd.js"></script>
...
이 스크립트는 모든 서비스를 포함하는 전역 assemblyai 변수를 생성합니다.
StreamingTranscriber 객체를 만드는 방법은 다음과 같습니다.
const { StreamingTranscriber } = assemblyai;
const transcriber = new StreamingTranscriber({
token: "[YOUR API에서 임시 인증 토큰을 생성하세요]",
...
IDE에서 타입 지원을 받으려면 JavaScript의 참조 타입를 참조하세요.
음성 인식 (Speech-To-Text)
오디오 및 비디오 파일 전사(Transcribe)하기
<details open>
<summary>공개 URL을 가진 오디오 파일 전사하기</summary>
전사본(transcript)을 생성할 때, 오디오 파일의 URL을 전달하거나 파일을 직접 업로드할 수 있습니다.
const audioFile = "https://assembly.ai/sports_injuries.mp3";
...
[!참고]
audio 속성으로 로컬 파일 경로(local file path), 스트림(stream), 또는 버퍼(buffer)를 전달할 수도 있습니다.
transcribe는 전사 작업(transcription job)을 큐에 넣고, 상태(status)가 completed 또는 error가 될 때까지 폴링(polling)합니다.
전사본이 준비될 때까지 기다리고 싶지 않다면, submit을 사용할 수 있습니다:
let transcript = await client.transcripts.submit({
audio: "https://assembly.ai/espn.m4a",
speech_models: ["universal-3-5-pro", "universal-2"],
...
</details>
<details>
<summary>로컬 오디오 파일 전사하기</summary>
전사본을 생성할 때, 오디오 파일의 URL을 전달하거나 파일을 직접 업로드할 수 있습니다.
let transcript = await client.transcripts.transcribe({
audio: "./news.mp4",
...
참고:
audio 속성으로 파일 URL, 스트림(stream), 또는 버퍼(buffer)를 전달할 수도 있습니다.
transcribe는 전사 작업(transcription job)을 큐에 넣고, 상태(status)가 completed 또는 error가 될 때까지 폴링(polling)합니다.
전사본이 준비될 때까지 기다리고 싶지 않다면, submit을 사용할 수 있습니다:
let transcript = await client.transcripts.submit({
audio: "./news.mp4",
speech_models: ["universal-3-5-pro", "universal-2"],
...
</details>
<details>
<summary>추가 음성 이해 모델 활성화하기</summary>
트랜스크립션 옵션(transcription options)을 사용하여 저희의 모든 음성 이해 모델(Speech Understanding models) 중 하나를 활성화함으로써 오디오에서 더 많은 통찰력을 추출할 수 있습니다. 예를 들어, 누가 무엇을 말했는지 감지하기 위해 화자 분리(Speaker diarization) 모델을 활성화하는 방법은 다음과 같습니다.
import { AssemblyAI } from "assemblyai";
const client = new AssemblyAI({
...
<details>
<summary>트랜스크립트 가져오기</summary>
이 코드는 현재 상태의 트랜스크립트 객체를 반환합니다. 트랜스크립트가 여전히 처리 중인 경우, status 필드는 queued 또는 processing일 것입니다. 트랜스크립트 처리가 완료되면, status 필드는 completed가 됩니다.
const transcript = await client.transcripts.get(transcript.id);
만약 .submit()을 사용하여 트랜스크립트를 생성했다면, .waitUntilReady()를 사용해 트랜스크립트의 status가 completed 또는 error가 될 때까지 폴링(poll)할 수 있습니다:
const transcript = await client.transcripts.waitUntilReady(transcript.id, {
pollingInterval: 1000,
...
</details>
<details>
<summary>문장 및 단락 가져오기</summary>
const sentences = await client.transcripts.sentences(transcript.id);
const { paragraphs } = await client.transcripts.paragraphs(transcript.id);
...
</details>
<details>
<summary>자막 가져오기</summary>
const charsPerCaption = 32;
let srt = await client.transcripts.subtitles(transcript.id, "srt");
srt = await client.transcripts.subtitles(transcript.id, "srt", charsPerCaption);
...
</details>
<details>
<summary>트랜스크립트 목록 보기</summary>
이 코드는 사용자가 생성한 트랜스크립트 페이지를 반환합니다.
const page = await client.transcripts.list();
또한 모든 페이지에 대해 페이징(paginate)할 수도 있습니다.
let previousPageUrl: string | null = null;
do {
const page = await client.transcripts.list(previousPageUrl);
...
</details>
⚠️ [!NOTE]
모든 페이지를 순회(paginate)하려면 page.page_details.prev_url을 사용해야 합니다. 그 이유는 트랜스크립트가 생성 날짜 및 시간에 따라 내림차순으로 반환되기 때문입니다. 첫 번째 페이지는 가장 최근의 트랜스크립트를 담고 있으며, 각 "이전(previous)" 페이지는 더 오래된 트랜스크립트를 포함합니다.
</details>
<details>
<summary>트랜스크립트 삭제하기</summary>
const res = await client.transcripts.delete(transcript.id);
</details>
오디오 동기식 트랜스크립션 (Transcribe audio synchronously)
client.sync는 오디오를 단일 라이브 연결(live connection)을 통해 전송하고 완료된 트랜스크립트를 한 번의 왕복(round trip)으로 반환합니다. 작업 ID나 폴링(polling)이 필요 없습니다. transcribe()는 이미 가지고 있는 클립을 단일 청크로 해당 연결을 통해 전송하며, transcribeLive() / openLive()는 녹음되는 동안 실시간으로 업로드합니다. 답변을 인라인(inline)으로 받고 싶은 짧은 클립에 사용하고, 장문 오디오, URL 또는 sync API가 노출하지 않는 풍부한 오디오 지능 기능에는 client.transcripts를 사용하십시오.
const result = await client.sync.transcribe("./call.wav");
console.log(result.text, result.session_id);
입력은 로컬 파일 경로, 원시 오디오 바이트(raw audio bytes), Blob, 또는 읽기 가능한 스트림(readable stream)일 수 있지만, URL은 안 됩니다.
<details>
<summary>트랜스크립트 구성하기</summary>
const result = await client.sync.transcribe("./call.wav", {
prompt: "Transcribe verbatim. Preserve disfluencies.",
keyterms_prompt: ["AssemblyAI", "Lemur"],
...
</details>
원시 S16LE PCM 오디오는 sample_rate와 channels가 필요하며, WAV 파일은 헤더에서 이를 읽어옵니다.
const result = await client.sync.transcribe(rawPcmBytes, {
sample_rate: 16_000,
channels: 1,
...
</details>
<details>
<summary>단어 타임스탬프 가져오기</summary>
단어 타임스탬프는 옵트인(opt-in) 기능입니다. 기본적으로 result.words의 각 단어는 text와 confidence만 포함하며, start/end는 없습니다. timestamps: true를 설정하면 약간의 지연 시간 비용을 감수하고 정확한 단어별 타이밍(per-word timings)을 얻을 수 있습니다.
</details>
<details>
<summary>연결 사전 예열하기</summary>
The sync API는 단일 요청/응답 방식이므로, 온디맨드(on demand)로 연결하는 transcribe()를 사용하면 전체 DNS + TCP + TLS 핸드셰이크 과정이 중요 경로(critical path)에 포함됩니다. 오디오가 들어올 것을 알게 되는 즉시 warm()을 호출하세요. 예를 들어 녹음 중일 때 미리 호출하여 다음 transcribe()가 열린 연결을 재사용하도록 합니다.
await client.sync.warm();
const audio = await recordUntilDone();
const result = await client.sync.transcribe(audio);
</details>
<details>
<summary>녹음되는 실시간 오디오 전사하기 (`openLive()`)</summary>
openLive()는 오디오가 존재하기 전에 요청을 시작하고, 청크(chunks)가 도착함에 따라 업로드합니다. 따라서 인증, 업로드 과정, 그리고 마지막 세그먼트를 제외한 모든 음성 세그먼트는 사용자가 녹음하는 동안 해결됩니다. 화자가 멈춘 후에 기다릴 것은 최종 세그먼트뿐입니다. 이 기능은 콜백 기반 소스(callback-driven sources)에 최적화되어 있습니다: 마이크로폰 라이브러리, WebRTC 트랙, 전화 통신 미디어 스트림 등이 해당됩니다.
import { spawn } from "node:child_process";
import { AssemblyAI } from "assemblyai";
...
result()는 서버가 요청을 거부할 때 SyncTranscriptError로 거부합니다. 업로드 자체를 중단하려면(사용자가 취소했거나 통화가 끝난 경우) await session.abort()를 사용하세요. 이 경우, 그 후에 result()가 거부됩니다. session.closed는 오디오가 종료되었는지 여부를 보고하며, session.stream()은 WritableStream을 반환하여 웹 스트림의 오디오를 바로 파이프(pipe)할 수 있게 합니다 (source.pipeTo(session.stream())). 세션이 닫히면 자동으로 세션도 닫힙니다.
이것은 스트리밍 API가 아닙니다. client.streaming은 화자가 여전히 말하고 있을 때 단어들을 반환하는 반면, 실시간 동기 업로드(live sync upload)는 오디오가 끝날 때 하나의 완료된 전사본을 반환합니다. 아래의 주의사항들은 openLive()에 동일하게 적용됩니다.
</details>
<details>
<summary>스트림에서 실시간 오디오 전사 실행 (`transcribeLive()`)</summary>
transcribeLive()는 이미 스트림인 소스(비동기 이터러블 (Node streams 포함), 동기 이터러블, 또는 웹 ReadableStream<Uint8Array>)를 위한 openLive()의 풀 스타일 대응물입니다. 이는 transcribe()와 동일한 설정을 사용하며 동일한 전사 결과를 반환합니다.
디스크에 이미 존재하는 파일은 적절하지 않은 소스입니다. 이를 스트리밍하는 방식은 한 번에 업로드하는 transcribe()보다 느립니다. 또한, 실시간 경로는 바이트(bytes), Blob 또는 이름으로 지정된 경로를 거부합니다.:
