Copy for your agent
In a hurry? Paste this into a coding agent that can run shell commands on your Mac, and put your file's path on the last line. The steps below explain each part.
Transcribe a local recording with AFK, a Mac app that is also a command-line tool. 1. Find the command. Use `afk` if it is on PATH. Otherwise call /Applications/AFK.app/Contents/MacOS/AFK directly. Run it with --help to confirm it works. 2. Install AFK's Agent Skill with `afk install-agent-skill`, then read ~/.agents/skills/afk-transcription/SKILL.md and follow it. 3. Transcribe one file per command, with the path in quotes: afk transcribe "FILE" > "FILE.txt". The transcript is on stdout. Progress and errors are on stderr. 4. Add --srt for subtitles or --json for words with timings. For a folder, loop over the files and run one command per file. 5. If a command exits with a non-zero status, show me what it printed on stderr, and do not present a partial transcript as complete. Video must be MP4, MOV, or M4V with an audio track. Transcription runs on this Mac. Do not send the transcript to an online service unless I ask. The file:
Install the bundled skill
The signed AFK app includes a short afk-transcription Agent Skill. Install it with the button on the Automation screen, or from Terminal:
$ afk install-agent-skill
The command copies the skill to ~/.agents/skills/afk-transcription. An identical copy is left alone. A different existing copy is not overwritten unless you deliberately pass --force.
Download the bundled Agent Skill (SKILL.md) →
Give the agent a bounded workflow
- Pass one quoted local path to
afk transcribe. - Keep transcript output on stdout and diagnostics on stderr.
- Use
--jsonor--srtwhen the next step needs structured output. - Use a shell loop for a folder; AFK does not provide a batch flag or MCP server.
$ afk transcribe recording.m4a > recording.txt $ afk transcribe lesson.mp4 --srt > lesson.srt
Check what came back
The exit status says how the command went, so an agent doesn't have to guess from the text:
- 0 means the transcript on stdout is complete.
- 1 means something failed. On a long recording, AFK can still print the parts it could transcribe; the warning on stderr gives the missing time range, and
--jsonlists it in anissuesarray. Keep that warning with the result. - 2 means the command was written wrong: a missing file path or an unknown flag.
Respect the input boundary
The CLI accepts AFK's supported audio inputs and video as .mp4, .mov, or .m4v with an audio track. It extracts the video's audio into a temporary directory and removes it after the command. Other video containers such as MKV, WebM, or AVI are not supported. An agent should not promise another container or send a transcript to a networked tool without an explicit instruction.
Keep local and network steps distinct
First-run model preparation may need the network. Once the model is ready, recognition and file reading run locally. A shell command or agent may choose to send stdout somewhere else; that is a separate action outside AFK's transcription path.
Troubleshooting
The agent says afk: command not found
The afk alias in ~/.zshrc exists in your own Terminal windows. An agent's shell often doesn't load it. Tell the agent to call /Applications/AFK.app/Contents/MacOS/AFK directly. The Automation screen shows the exact path for your copy of the app.
The agent doesn't pick up the skill
The skill is installed at ~/.agents/skills/afk-transcription. If your agent reads skills from a different folder, copy that folder there, or paste the prompt at the top of this page instead.
The install says a different skill already exists
AFK won't replace a copy that differs from the bundled one, in case you edited it. Review the existing copy, then run afk install-agent-skill --force if you want to replace it.
The video is MKV, WebM, or AVI
AFK reads MP4, MOV, and M4V video. Convert other containers to one of those first, then transcribe the converted file.
The command exited with status 1 but printed a transcript
Part of a long recording couldn't be transcribed. The warning on stderr gives the missing time range. Treat the result as partial.
The first run is slow or needs the internet
The first command prepares the speech model, which may need a download. After that, transcription runs on your Mac. If setup fails, see model setup and CLI problems in troubleshooting.
Agent handoff: the CLI guide owns flags, streams, and exit behavior. This page owns the skill and the workflow around it.