speech-video-transcriber

turn a local media file into a markdown transcript with minimal local compute.

the intended path is:

extract compact mono audio with ffmpeg
send that audio to OpenAI transcription
write a markdown transcript into ../transcriptions/ relative to the skills/ directory

for this repo, that means outputs land in:

/Users/rami/Documents/life-os/ai-agents-config/transcriptions/

when to use it

use this skill when the user wants any of the following from a local media file:

a transcript from a speaking video
a transcript from an audio file
a markdown transcript saved to disk for later analysis
a first pass before communication coaching, speaking feedback, vocabulary analysis, or camera-performance review

if the user asks for speaking feedback but no transcript exists yet, use this skill first so later steps can work from a clean markdown source.

backends

local (default when user mentions whisper or offline):

flag: --local
model: small (uses ~/.cache/whisper/small.pt — no download needed if already cached)
no API key required
whisper handles audio internally, no chunking needed

cloud (default otherwise):

model: gpt-4o-transcribe
requires OPENAI_API_KEY
auto-chunks audio if file exceeds 24 MB upload limit
only switch to gpt-4o-mini-transcribe if the user explicitly wants the cheaper model

defaults

default output folder: ai-agents-config/transcriptions/
default preprocessing: mono mp3 at 16 kHz and 48 kbps

required setup

from /Users/rami/Documents/life-os/ai-agents-config/skills:

uv pip install -r speech-video-transcriber/scripts/requirements.txt

the machine also needs:

ffmpeg
OPENAI_API_KEY

workflow

resolve the media path to an absolute path before running anything
if the user gives a language hint, pass --language
if the file contains names, jargon, brand terms, or unusual words, pass a short --prompt with those tokens to improve recognition
run the script
return the markdown path you wrote

command

local (no API key):

cd /Users/rami/Documents/life-os/ai-agents-config/skills
uv run python speech-video-transcriber/scripts/transcribe_video.py "/absolute/path/to/video.mov" --local

cloud (OpenAI API):

cd /Users/rami/Documents/life-os/ai-agents-config/skills
uv run python speech-video-transcriber/scripts/transcribe_video.py "/absolute/path/to/video.mov"

common options:

# local with language hint
uv run python speech-video-transcriber/scripts/transcribe_video.py \
  "/absolute/path/to/video.mov" \
  --local \
  --language en

# cloud with jargon hint
uv run python speech-video-transcriber/scripts/transcribe_video.py \
  "/absolute/path/to/video.mov" \
  --language en \
  --prompt "rami, chalant, purpose os, posthog" \
  --model gpt-4o-transcribe

# save to specific path
uv run python speech-video-transcriber/scripts/transcribe_video.py \
  "/absolute/path/to/video.mov" \
  --local \
  --output "/path/to/output.md"

output contract

the script writes one markdown file to the shared transcriptions directory and prints the final path.

the markdown includes:

source media path
generation timestamp
model used
optional language hint
chunk count
full transcript text

if a file with the same name already exists, the script appends a timestamp suffix instead of overwriting it.

examples

example 1

user request: transcribe /Users/rami/Documents/life-os/speech/founder-story-take-01.mov

run:

cd /Users/rami/Documents/life-os/ai-agents-config/skills
uv run python speech-video-transcriber/scripts/transcribe_video.py \
  "/Users/rami/Documents/life-os/speech/founder-story-take-01.mov"

example 2

user request: make a transcript of /Users/rami/Documents/life-os/speech/camera-practice/clarity.mp4 and keep the names right. the language is english.