Package Exports

transcribly
transcribly/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (transcribly) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Transcribly

Transcribe YouTube videos and local audio/video files from your terminal using the OpenAI Whisper API.

npx transcribly https://www.youtube.com/watch?v=VIDEO_ID

Transcript prints to your terminal and saves to ./text/.

Prerequisites

Node.js 18+
FFmpeg — must be available in your PATH
Python 3.8+ — required by yt-dlp for YouTube downloads
OpenAI API key — get one at platform.openai.com/api-keys

Run transcribly --doctor to verify everything is set up correctly.

Install FFmpeg

# macOS
brew install ffmpeg

# Linux (Debian/Ubuntu)
sudo apt install ffmpeg

# Windows (Chocolatey)
choco install ffmpeg

# Windows (winget)
winget install ffmpeg

API Key Setup

# Environment variable
export OPENAI_API_KEY="sk-..."

# Or pass it directly
npx transcribly <url> --api-key sk-...

# Or add to a .env file in your working directory
OPENAI_API_KEY=sk-...

Run transcribly --setup for an interactive setup prompt.

Usage

Transcribe a YouTube video

npx transcribly https://www.youtube.com/watch?v=VIDEO_ID

Transcribe a local file

npx transcribly file ./interview.mp3

Use the transcript with an AI agent

Each agent CLI handles piped stdin a little differently. Use whichever pattern matches your tool — they all end with the agent processing the transcript.

Codex — pipe directly, stdin becomes the prompt:

npx transcribly https://www.youtube.com/watch?v=VIDEO_ID | codex exec --skip-git-repo-check

GitHub Copilot CLI — pipe directly without a -p flag:

npx transcribly https://www.youtube.com/watch?v=VIDEO_ID | copilot

Claude — Claude's CLI bails on slow stdin (3-second timeout), so write the transcript to a file first, then feed it in. Use the --out-file flag for a clean one-liner:

npx transcribly https://www.youtube.com/watch?v=VIDEO_ID --out-file /tmp/t.txt && \
  claude -p "Summarise this" < /tmp/t.txt

The file-based pattern also works as a universal fallback for any agent or downstream tool (grep, jq, your own scripts, etc.).

Save as JSON

npx transcribly https://www.youtube.com/watch?v=VIDEO_ID --format json

Pipe output to a file

npx transcribly https://www.youtube.com/watch?v=VIDEO_ID > transcript.txt

Options

Option	Description	Default
`-o, --output <dir>`	Output directory for transcript files	`./text`
`--out-file <path>`	Write transcript to a specific file (overrides `--output`)	—
`-f, --format <format>`	Output format: `txt` or `json`	`txt`
`-k, --api-key <key>`	OpenAI API key (overrides env var)	—
`--doctor`	Check all system dependencies	—
`--setup`	Set up OpenAI API key interactively	—

Output Format

Text (default) — plain transcript saved to ./text/<video-id>.txt

JSON — structured output saved to ./text/<video-id>.json:

{
  "audioFile": "/path/to/audio.mp3",
  "transcript": "The full transcript text..."
}

Supported File Formats

mp3 mp4 wav webm m4a ogg flac mpeg mpga

Files larger than 24 MB are automatically split into chunks before transcription.

Global Install

npm install -g transcribly
transcribly https://www.youtube.com/watch?v=VIDEO_ID

Programmatic Usage

const { transcribe } = require("transcribly/dist/transcriber");

(async () => {
  const result = await transcribe("./audio.mp3", process.env.OPENAI_API_KEY);
  console.log(result.transcript);
})();

License

MIT

transcribly