CLI로 사용하기

transcript1 명령 뒤에 영상 링크나 파일 경로를 넣으세요. YouTube, X, TikTok, Instagram, Facebook, Bluesky와 로컬 오디오·영상 파일을 텍스트로 변환할 수 있어요. 추가 플랫폼은 아래의 버전 조건을 확인하세요. 링크별 지원 범위는 지원 링크와 변환 옵션에 있어요. CLI는 단독 실행 파일이므로 Node.js 없이 설치할 수 있어요.

YouTube 외 소셜 링크를 쓰려면 CLI 1.2.0 이상이 필요해요. 1.1.0 이하는 YouTube 링크만 지원하며 다른 링크는 서버에 보내기 전에 거부해요. transcript1 update로 업데이트하세요.

1.2.0은 처음 지원한 여섯 플랫폼의 최소 버전이에요. Twitch, Dailymotion, Pinterest, LinkedIn, Snapchat을 쓰려면 해당 플랫폼 지원이 추가된 릴리스가 필요해요. 구버전에서는 링크를 서버에 보내기 전에 거부할 수 있어요.

공개 게시물만 사용할 수 있고, 영상이 여러 개면 첫 번째 영상만 변환해요. 단축 링크의 지원 형식과 한도는 지원 링크와 변환 옵션에서 확인하세요.

CLI 설치하기

macOS와 Linux의 x64·ARM64 환경에서는 아래 명령을 실행하세요.

curl -fsSL https://transcript1.com/install.sh | sh

실행 파일은 ~/.local/bin에 설치해요. PATH 설정이 필요하면 설치 후 안내해 드려요. 설치 폴더를 바꾸려면 TRANSCRIPT1_INSTALL_DIR을 지정하세요.

짧은 명령어 t1도 함께 설치해요. zsh에서는 ~/.zshrc에 alias transcript1='noglob transcript1'을 추가해 ?가 있는 링크도 따옴표 없이 쓸 수 있게 해요. 셸 설정 파일을 수정하지 않으려면 TRANSCRIPT1_NO_MODIFY_SHELL=1을 설정하세요.

Windows x64에서는 PowerShell에서 아래 명령을 실행하세요.

irm https://transcript1.com/install.ps1 | iex

설치 위치는 %LOCALAPPDATA%\Programs\transcript1이에요. 짧은 명령어인 t1.cmd를 추가하고 설치 폴더를 사용자 PATH에 등록해요. 설치 후 새 터미널을 열어 사용하세요.

계정 연결하기

먼저 로그인 명령을 실행하세요.

transcript1 login

브라우저에서 transcript1.com을 열어요. SSH로 접속했거나 화면이 없는 환경이면 대신 링크를 출력해요. 터미널과 웹페이지의 코드가 같은지 확인하고 “Approve”를 누르세요. 승인하면 CLI가 transcript1 CLI (<computer name>)이라는 키를 저장해요. 대시보드의 “API keys” 페이지에서도 이 키를 확인할 수 있어요.

링크만 받고 브라우저를 자동으로 열지 않으려면 transcript1 login --no-browser를 실행하세요.

기존 API 키로 연결하려면 transcript1 login --with-key를 실행한 뒤 키를 붙여넣으세요. transcript1 login < key.txt처럼 표준 입력으로 전달할 수도 있어요.

CI나 에이전트 환경에서는 TRANSCRIPT1_API_KEY를 설정하세요. 이 값이 있으면 저장된 키 대신 사용해요. 터미널이나 키가 없는 에이전트도 transcript1 login < /dev/null로 승인 링크를 받아 사용자에게 전달할 수 있어요.

transcript1 logout을 실행하면 CLI 키를 폐기하고 컴퓨터에 저장한 키도 지워요. 서버에서 폐기하지 못한 경우에는 로컬 키를 지운 뒤 “API keys” 페이지에서 직접 폐기하도록 안내해요. 직접 붙여넣은 키는 로그아웃과 별도로 해당 페이지에서 폐기해야 해요.

영상 링크 변환하기

transcript1 'https://youtu.be/dQw4w9WgXcQ'

스크립트가 준비되면 텍스트를 stdout에 출력해요. YouTube, X, TikTok, Bluesky, Dailymotion, LinkedIn에서는 영상 원본 언어의 자막을 우선 사용하고, 사용할 자막이 없으면 AI 텍스트 변환을 실행해요. 기다리는 동안의 진행 상황은 stderr에 표시해요.

zsh에서는 링크를 따옴표로 감싸는 게 안전해요. 따옴표가 없으면 &에서 명령이 나뉘어요. ?도 설치 시 추가한 별칭을 쓰지 않으면 파일 검색 패턴으로 해석해요.

로컬 파일 변환하기

transcript1 interview.mp3
transcript1 -f srt -o interview.srt interview.mp3

파일 경로를 주면 CLI가 업로드한 뒤 스크립트가 완성될 때까지 기다려요. 최대 크기는 2GB(2,000,000,000바이트)예요. mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm, mkv 확장자를 지원해요.

여러 파일과 링크 한꺼번에 처리하기

파일·링크를 여러 개 나열하거나 폴더 경로를 넣으세요.

transcript1 interview.mp3 lecture.mp4
transcript1 -o transcripts/ ./recordings
transcript1 --jobs 4 -o transcripts/ interview.mp3 'https://youtu.be/dQw4w9WgXcQ'

recordings/*.mp3 같은 파일 패턴은 Windows에서도 사용할 수 있어요. 폴더를 지정하면 그 폴더 바로 아래의 미디어 파일을 이름순으로 처리해요. 입력이 여러 개면 기본적으로 ./transcripts에 각각의 스크립트를 저장해요. 동시 처리 수는 --jobs로 1~20 사이에서 지정하세요. 기본값은 2예요.

입력에 -를 넣으면 stdin에서 한 줄에 하나씩 링크나 파일 경로를 읽어요. macOS와 Linux 셸에서는 아래처럼 파일 목록을 전달할 수 있어요.

transcript1 -o transcripts/ - < inputs.txt

빈 줄이나 #로 시작하는 줄은 무시해요. 같은 입력이 반복돼도 한 번만 처리해요.

입력이 하나면 -o에 저장할 파일 이름을 지정하세요. 다만 기존 폴더를 가리키거나 경로가 /로 끝나면 폴더로 사용해요. 입력이 여러 개일 때는 -o가 저장 폴더를 뜻해요. 폴더가 없으면 자동으로 만들어요.

YouTube 링크나 로컬 파일의 스크립트가 지정한 경로에 이미 있으면 해당 입력을 건너뛰어요. 다시 변환해서 덮어쓰려면 --overwrite를 붙이세요.

transcript1 --overwrite -o transcripts/ ./recordings

출력 형식과 변환 옵션

화자 분리와 타임스탬프를 함께 적용하는 예제예요.

transcript1 --speakers --timestamps --language en interview.mp3

--speakers와 --source captions는 함께 사용할 수 없어요. auto에서 화자 분리를 켜면 자막을 건너뛰고 음성을 변환해요. YouTube와 X의 기존 자막 처리는 그대로이며 TikTok, Bluesky, Dailymotion, LinkedIn에서도 자막을 가져올 수 있어요. YouTube 외 플랫폼은 자동 생성 자막도 타임스탬프를 세그먼트 단위로만 제공해요(words: null). 플랫폼별 기능과 언어 선택 기준은 지원 링크와 변환 옵션을 확인하세요.

스크립트와 에이전트에서 자동화하기

에이전트가 셸을 사용할 수 있다면 CLI를 설치하고 TRANSCRIPT1_API_KEY를 설정하세요. 이후 transcript1 <link>나 transcript1 <file>을 실행하면 돼요. MCP 클라이언트로 연결하려면 MCP 서버 연결을 확인하세요.

자동화에는 --json을 사용하세요. 입력 하나의 처리가 끝날 때마다 stdout에 JSON을 한 줄씩 출력해요. 진행 상황, 요약, 업데이트 알림은 표시하지 않아요.

transcript1 --json 'https://youtu.be/dQw4w9WgXcQ'

완료된 입력의 JSON은 API 작업 객체에 input, reused를 더한 형태예요. 스크립트를 파일에 저장했다면 transcript 대신 file 경로를 넣어요. 작업 ID가 생기기 전에 오류가 나면 input과 error 객체를 출력하며, 오류 안에는 code, message가 있어요.

건너뛴 입력에는 input과 skipped가 있어요. 건너뛴 이유는 exists 또는 out_of_minutes이고, 해당하는 경우 file도 포함해요. exists는 YouTube 링크와 로컬 파일에만 사용해요.

입력이 하나이고 -o가 없으면 --json은 객체에 스크립트까지 담고 -f는 무시해요. 입력이 여러 개이고 -o가 없으면 스크립트 파일은 ./transcripts에 저장해요. 이때 각 JSON 줄에는 transcript 대신 file이 들어가요. 파일로 저장할 때의 형식은 항상 -f로 정해요.

스크립트와 오류만 출력하고 진행 상황·요약을 숨기려면 -q나 --quiet를 쓰세요.

작업만 시작하고 스크립트는 나중에 가져올 수도 있어요.

transcript1 --no-wait interview.mp3
transcript1 get <id>

첫 명령에서 받은 ID를 <id>에 넣으세요. --no-wait는 ID와 상태만 출력해요. --json을 함께 쓰면 객체를 출력해요. get은 작업이 끝날 때까지 기다려 가져오며, -f, -o, --timestamps, --no-wait, --json, -q 옵션을 지원해요.

최신 버전으로 업데이트하기

transcript1 update

stderr가 터미널에 연결돼 있으면 최대 24시간에 한 번 새 버전을 확인하고 업데이트 알림을 표시해요. 버전 확인 자체를 끄려면 TRANSCRIPT1_NO_UPDATE_CHECK=1을 설정하세요. --json이나 -q를 사용할 때도 업데이트 알림은 표시하지 않아요.

종료 코드

전체 명령과 옵션은 transcript1 --help로 확인하세요. 인자 없이 transcript1만 실행해도 도움말이 나와요.