ml-explore / ml-explore/mlx-examples

[whisper] `KeyError: 'words'` on transcription (with `--task translate`)

Open Beginner friendly
#1,418 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
9k
Forks
1.2k
PR merge metrics
No merged PRs in 30d

Description

I ran into the error below trying to create .srt subtitles for an MP4.

❯ mlx_whisper '20260416_170014.mp4'  --task translate  --model mlx-community/whisper-large-v3-mlx --output-format srt --verbose False --condition-on-previous-text False
…
Traceback (most recent call last):
  File "lib/python3.13/site-packages/mlx_whisper/cli.py", line 249, in main
    writer(result, output_name, **writer_args)
    ~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "lib/python3.13/site-packages/mlx_whisper/writers.py", line 51, in __call__
    self.write_result(result, file=f, options=options, **kwargs)
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "lib/python3.13/site-packages/mlx_whisper/writers.py", line 209, in write_result
    for i, (start, end, text) in enumerate(
                                 ~~~~~~~~~^
        self.iterate_result(result, options, **kwargs), start=1
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ):
    ^
  File "lib/python3.13/site-packages/mlx_whisper/writers.py", line 147, in iterate_result
    for subtitle in iterate_subtitles():
                    ~~~~~~~~~~~~~~~~~^^
  File "lib/python3.13/site-packages/mlx_whisper/writers.py", line 97, in iterate_subtitles
    last: float = get_start(result["segments"]) or 0.0
                  ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
  File "lib/python3.13/site-packages/mlx_whisper/writers.py", line 31, in get_start
    return next(
        (w["start"] for s in segments for w in s["words"]),
        segments[0]["start"] if segments else None,
    )
  File "lib/python3.13/site-packages/mlx_whisper/writers.py", line 32, in <genexpr>
    (w["start"] for s in segments for w in s["words"]),
                                           ~^^^^^^^^^
KeyError: 'words'
Skipping 20260416_170014.mp4 due to KeyError: 'words'

Luckily it was an easy investigation to gin up a fix for my use-case, but I admit I didn't really stick my head all the way into the whisper demo, so my fix might be flawed. I'll share the PR, but there is this bug in evidence, regardless.

Basically, subtitle generation enters word-level mode when only segments[0] has "words", but get_start() iterates every segment's s["words"] → KeyError when later segments omit "words", as is common with --task translate.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in mlx_whisper/writers.py, especially get_start and iterate_subtitles, and reproduce the reported command with --task translate and --output-format srt. Trace how subtitle generation handles segments with and without a words key. Done means translation transcription can produce an SRT without a KeyError when later segments omit words.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
audio-video-rtc
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.