faster-whisper metadata_errors TypeError, av 18.1.0으로 전사 성공
PyPI faster-whisper 1.2.1로 짧은 한국어 mp3를 넘기면, PyAV 19.0.1에서는 open()이 metadata_errors라는 키워드를 받지 않아 TypeError로 멈춥니다. 공개 이슈에는 Windows와 Python 3.14.8, av 19.0.0이 적혀 있고, 이 글의 재현은 Debian GNU/Linux 13, Python 3.12.15, av 19.0.1입니다. 환경은 달라도 오류 문장은 같습니다. 서버의 한국어 전사 작업에 쓸 수 있는지는 Debian GNU/Linux 13의 CPU 환경에서 짧은 mp3를 처리할 수 있는지와 의존성 조합에 따른 오류로 가렸고, 그 과정을 세 스크립트로 실행해 기록했습니다.
먼저 PyPI의 faster-whisper 1.2.1과 av 19.0.1로 traceback을 띄웠습니다. 그다음 1.2.1은 그대로 두고 av만 18.1.0으로 고정해 language=ko 전사를 끝냈고, av 19.0.1을 다시 올린 뒤 업스트림 커밋 2ce7f9d를 설치해 한 번 더 전사했습니다. 숫자와 오류 문장은 실행 로그에 있는 것만 옮겼습니다.
PyAV 19.0.1이 metadata_errors 키워드를 거부하는 장면
실행일과 도구 버전은 재현 스크립트 출력 그대로입니다. 모델은 네트워크 이름을 새로 받지 않고, 로컬 디렉터리 models/faster-whisper-tiny를 넘겼습니다. 그 디렉터리에는 config.json, model.bin, tokenizer.json, vocabulary.txt가 있습니다.
| 항목 | 측정값 |
|---|---|
| 실행일 | 2026-10-14 |
| OS | Debian GNU/Linux 13 (trixie) |
| 커널 | Linux 6.12.94+ x86_64 |
| nproc | 8 |
| uv | 0.13.0 |
| Python | 3.12.15 |
| ffprobe | 7.1.5-0+deb13u1 |
| faster-whisper | 1.2.1 |
| av | 19.0.1 |
| ctranslate2 | 4.8.3 |
| onnxruntime | 1.31.0 |
| 음성 | mp3, sample_rate 24000, channels 1, duration 11.736000 |
음성 길이와 코덱은 아래 명령으로 읽었습니다. 출력의 codec_name=mp3, sample_rate=24000, channels=1로 입력 조건부터 고정해 둡니다. duration=11.736000은 뒤에서 전사 결과의 길이와 맞대어 볼 기준일 뿐, 처리에 걸린 시간이 아닙니다.
ffprobe -v error -select_streams a:0 -show_entries stream=codec_name,sample_rate,channels -show_entries format=duration -of default=noprint_wrappers=1 audio/hello-ko.mp3가상환경 venv의 Python도 3.12.15입니다. PyPI 배포물과 똑같이 맞추려고 faster-whisper를 지웠다가 1.2.1을 다시 설치했고, av는 19.0.1로 지정했습니다. 버전은 src/versions.py가 찍고, 마지막 검색으로 설치된 호출부가 metadata_errors를 넘기는지까지 봅니다.
uv pip uninstall -p venv faster-whisper || true
uv pip install -p venv 'faster-whisper==1.2.1'
uv pip install -p venv 'av==19.0.1'
venv/bin/python src/versions.py
grep -n metadata_errors venv/lib/python3.12/site-packages/faster_whisper/audio.py설치된 1.2.1의 faster_whisper/audio.py 46행은 av.open에 metadata_errors="ignore"를 조건 없이 넘깁니다. 점검 스크립트가 같은 음성 파일을 PyAV로 열고 19.0.1의 독스트링을 찍었는데, 거기에 그 인자는 없습니다. doc_has_metadata_errors는 False이고, 키워드를 넣으면 TypeError, 키워드 없이 열면 plain_open=ok입니다. 이렇게 열었을 때 코덱 이름은 mp3float, rate는 24000, channels는 1이고, ffprobe의 codec_name은 mp3입니다.
import av
print("av_version", av.__version__)
doc = av.open.__doc__ or ""
print("doc_has_metadata_errors", "metadata_errors" in doc)
try:
container = av.open(
"audio/hello-ko.mp3",
mode="r",
metadata_errors="ignore",
)
container.close()
print("kw_open=ok")
except TypeError as exc:
print("kw_open=TypeError:", exc)
with av.open("audio/hello-ko.mp3", mode="r") as container:
stream = container.streams.audio[0]
print(
"plain_open=ok",
"codec",
stream.codec_context.name,
"rate",
stream.sample_rate,
"channels",
stream.channels,
)사용자가 부르는 경로에서 오류는 WhisperModel.transcribe가 decode_audio를 호출할 때 납니다. 모델은 device="cpu", compute_type="int8", 언어는 ko, beam_size는 5입니다. 아래 코드는 세그먼트를 다 돈 뒤 언어, 길이, 합친 전사문을 찍기 때문에, 모델 생성이 된 것과 전사가 끝난 것을 갈라 볼 수 있습니다.
from faster_whisper import WhisperModel
model = WhisperModel(
"models/faster-whisper-tiny",
device="cpu",
compute_type="int8",
)
segments, info = model.transcribe(
"audio/hello-ko.mp3",
language="ko",
beam_size=5,
)
texts = []
for segment in segments:
line = "[%.2f -> %.2f] %s" % (segment.start, segment.end, segment.text.strip())
print(line)
texts.append(segment.text.strip())
print("language=" + info.language)
print("duration=%.3f" % info.duration)
print("TEXT=" + " ".join(texts))실행 명령은 venv/bin/python src/transcribe.py입니다. traceback은 transcribe.py 876행의 decode_audio 호출에서 audio.py 46행으로 내려가고, av/container/core.py 479행에서 끝납니다. 예외 문장은 TypeError: open() got an unexpected keyword argument 'metadata_errors'이고 transcribe_exit=1입니다.
=== reproduce metadata_errors ===
+ date --iso-8601=seconds
2026-10-14T13:40:07+09:00
+ grep '^PRETTY_NAME=' /etc/os-release
PRETTY_NAME="Debian GNU/Linux 13 (trixie)"
+ uname -srm
Linux 6.12.94+ x86_64
+ nproc
8
+ command -v nvidia-smi >/dev/null && nvidia-smi | head -n 1 || echo 'nvidia-smi: command not found'
nvidia-smi: command not found
+ uv --version
uv 0.13.0 (x86_64-unknown-linux-gnu)
+ "/home/user/.local/share/uv/python/cpython-3.12-linux-x86_64-gnu/bin/python3.12" --version
Python 3.12.15
+ ffprobe -version | head -n 1
ffprobe version 7.1.5-0+deb13u1 Copyright (c) 2007-2026 the FFmpeg developers
+ ffprobe -v error -select_streams a:0 -show_entries stream=codec_name,sample_rate,channels -show_entries format=duration -of default=noprint_wrappers=1 audio/hello-ko.mp3
codec_name=mp3
sample_rate=24000
channels=1
duration=11.736000
+ find models/faster-whisper-tiny -maxdepth 1 -type f -printf '%f %s\n' | sort
config.json 2249
model.bin 75538270
tokenizer.json 2203239
vocabulary.txt 459861
+ venv/bin/python --version
Python 3.12.15
+ cat > src/show_open.py << 'PY'
+ cat > src/transcribe.py << 'PY'
+ cat > src/versions.py << 'PY'
+ uv pip uninstall -p venv faster-whisper || true
Using Python 3.12.15 environment at: venv
Uninstalled 1 package in 5ms
- faster-whisper==1.2.1 (from git+https://github.com/SYSTRAN/faster-whisper.git@2ce7f9d7a9fbe315a5804a33bf7224d42e101174)
+ uv pip install -p venv 'faster-whisper==1.2.1'
Using Python 3.12.15 environment at: venv
⠋ Resolving dependencies... ⠙ Resolving dependencies... ⠋ Resolving dependencies... ⠙ Resolving dependencies... ⠹ Resolving dependencies... ⠹ faster-whisper==1.2.1 ⠹ ctranslate2==4.8.3 ⠹ huggingface-hub==2.2.0 ⠹ tokenizers==0.23.3 ⠹ onnxruntime==1.31.0 ⠹ av==19.0.1 ⠹ tqdm==4.70.1 ⠸ tqdm==4.70.1 ⠸ numpy==2.5.4 ⠸ pyyaml==6.0.3 ⠸ click==8.5.0 ⠸ filelock==4.1.1 ⠸ fsspec==2026.9.0 ⠸ hf-xet==1.7.0 ⠸ hf-xet==1.7.0 ⠸ httpx2==2.13.1 ⠼ httpx2==2.13.1 ⠼ httpcore2==2.13.1 ⠼ httpcore2==2.13.1 ⠼ packaging==26.3 ⠼ typing-extensions==4.16.0 ⠼ typing-extensions==4.16.0 ⠼ flatbuffers==25.12.19 ⠼ protobuf==7.36.2 ⠼ anyio==4.15.1 ⠼ typing-extensions==4.16.0 ⠼ anyio==4.15.1 ⠼ h11==0.16.0 Resolved 23 packages in 669ms
░░░░░░░░░░░░░░░░░░░░ [0/0] Installing wheels... ░░░░░░░░░░░░░░░░░░░░ [0/1] Installing wheels... ░░░░░░░░░░░░░░░░░░░░ [0/1] faster-whisper==1.2.1 ████████████████████ [1/1] faster-whisper==1.2.1 Installed 1 package in 6ms
+ faster-whisper==1.2.1
+ uv pip install -p venv 'av==19.0.1'
Using Python 3.12.15 environment at: venv
Checked 1 package in 1ms
+ venv/bin/python src/versions.py
faster-whisper==1.2.1
av==19.0.1
ctranslate2==4.8.3
onnxruntime==1.31.0
+ grep -n metadata_errors venv/lib/python3.12/site-packages/faster_whisper/audio.py
46: with av.open(input_file, mode="r", metadata_errors="ignore") as container:
+ venv/bin/python src/show_open.py
av_version 19.0.1
doc_has_metadata_errors False
kw_open=TypeError: open() got an unexpected keyword argument 'metadata_errors'
plain_open=ok codec mp3float rate 24000 channels 1
+ venv/bin/python src/transcribe.py
Traceback (most recent call last):
File "/home/user/whisper/run/src/transcribe.py", line 8, in <module>
segments, info = model.transcribe(
^^^^^^^^^^^^^^^^^
File "/home/user/whisper/run/venv/lib/python3.12/site-packages/faster_whisper/transcribe.py", line 876, in transcribe
audio = decode_audio(audio, sampling_rate=sampling_rate)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/user/whisper/run/venv/lib/python3.12/site-packages/faster_whisper/audio.py", line 46, in decode_audio
with av.open(input_file, mode="r", metadata_errors="ignore") as container:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "av/container/core.py", line 479, in av.container.core.open
TypeError: open() got an unexpected keyword argument 'metadata_errors'
transcribe_exit=1
repro_typeerror=yes재현 스크립트가 환경과 오류를 한 화면에 남긴 터미널입니다. av 19.0.1에서는 키워드를 넣은 열기가 TypeError로 실패하는데, 같은 파일을 키워드 없이 열면 plain_open=ok가 나옵니다. 전사는 transcribe_exit=1로 끝나니, 파일 경로를 의심하기 전에 호출 인자와 설치된 라이브러리가 서로 맞는지부터 봐야 합니다.
캡처의 transcribe.py와 가상환경 경로에는 작업 폴더 이름까지 보이지만, 본문은 같은 트레이스백을 /home/user/whisper 기준으로 줄여 옮겼습니다.
호출부와 라이브러리 버전이 어긋난 것이 원인입니다. PyAV 19.0.0 릴리즈 노트는 av.open에서 metadata_errors와 metadata_encoding 인자를 뺐다고 적고, 메타데이터는 UTF-8과 surrogateescape로 읽고 쓴다고 덧붙입니다. 이번에 설치한 19.0.1에서도 같은 키워드는 TypeError를 냅니다. 그런데 1.2.1은 제거 이전의 인자 이름을 46행에 그대로 남겨 두었습니다.
같은 증상이 SYSTRAN/faster-whisper 이슈 1589에 올라와 있습니다. 이슈 본문에는 python 3.14.8, windows, package av 19.0.0이 적혀 있고 workaround 줄은 av < 19입니다. 아래 해결 명령은 그 범위 안의 구체적인 버전인 av 18.1.0을 씁니다.
faster-whisper는 그대로, PyAV만 18.1.0으로 내려 전사 끝내기
해결 스크립트는 PyPI faster-whisper 1.2.1을 다시 깐 다음 av만 18.1.0으로 바꿉니다. 로그에는 - av==19.0.1과 + av==18.1.0이 남습니다. audio.py 46행의 키워드 호출은 손대지 않았으니, 호출부를 고치지 않고 의존성만 바꿔서 복구되는지를 보는 셈입니다.
uv pip uninstall -p venv faster-whisper || true
uv pip install -p venv 'faster-whisper==1.2.1'
uv pip install -p venv 'av==18.1.0'
venv/bin/python src/versions.py
grep -n metadata_errors venv/lib/python3.12/site-packages/faster_whisper/audio.py
venv/bin/python src/show_open.py
venv/bin/python src/transcribe.py18.1.0에서는 doc_has_metadata_errors가 True, kw_open=ok입니다. plain_open도 ok이고 codec, rate, channels는 재현 때와 같은 mp3float, 24000, 1입니다. 이어서 같은 transcribe.py가 세그먼트와 TEXT 줄을 찍고 language=ko, duration=11.736, transcribe_exit=0으로 끝납니다. 11.736은 ffprobe duration 11.736000과 같은 음성 길이이고, 전사 내용은 출력의 구간 시각과 TEXT를 함께 보며 확인했습니다.
=== pin av==18.1.0 and transcribe ===
+ date --iso-8601=seconds
2026-10-14T13:40:13+09:00
+ test -x venv/bin/python
+ test -f src/transcribe.py
+ test -f src/show_open.py
+ uv pip uninstall -p venv faster-whisper || true
Using Python 3.12.15 environment at: venv
Uninstalled 1 package in 2ms
- faster-whisper==1.2.1
+ uv pip install -p venv 'faster-whisper==1.2.1'
Using Python 3.12.15 environment at: venv
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0/0⠙ Resolving dependencies... ⠋ Resolving dependencies... ⠙ Resolving dependencies... ⠙ faster-whisper==1.2.1 ⠙ ctranslate2==4.8.3 ⠙ huggingface-hub==2.2.0 ⠙ tokenizers==0.23.3 ⠙ onnxruntime==1.31.0 ⠙ av==19.0.1 ⠙ tqdm==4.70.1 ⠙ numpy==2.5.4 ⠙ pyyaml==6.0.3 ⠙ click==8.5.0 ⠙ filelock==4.1.1 ⠙ fsspec==2026.9.0 ⠙ hf-xet==1.7.0 ⠙ hf-xet==1.7.0 ⠙ httpx2==2.13.1 ⠙ httpcore2==2.13.1 ⠙ httpcore2==2.13.1 ⠙ packaging==26.3 Resolved 23 packages in 6ms
░░░░░░░░░░░░░░░░░░░░ [0/0] Installing wheels... ░░░░░░░░░░░░░░░░░░░░ [0/1] Installing wheels... ░░░░░░░░░░░░░░░░░░░░ [0/1] faster-whisper==1.2.1 ████████████████████ [1/1] faster-whisper==1.2.1 Installed 1 package in 4ms
+ faster-whisper==1.2.1
+ uv pip install -p venv 'av==18.1.0'
Using Python 3.12.15 environment at: venv
⠋ Resolving dependencies... ⠙ Resolving dependencies... ⠋ Resolving dependencies... ⠙ Resolving dependencies... ⠙ av==18.1.0 ⠙ Resolved 1 package in 1ms
Uninstalled 1 package in 6ms
░░░░░░░░░░░░░░░░░░░░ [0/0] Installing wheels... ░░░░░░░░░░░░░░░░░░░░ [0/1] Installing wheels... ░░░░░░░░░░░░░░░░░░░░ [0/1] av==18.1.0 ████████████████████ [1/1] av==18.1.0 Installed 1 package in 268ms
- av==19.0.1
+ av==18.1.0
+ venv/bin/python src/versions.py
faster-whisper==1.2.1
av==18.1.0
ctranslate2==4.8.3
onnxruntime==1.31.0
+ grep -n metadata_errors venv/lib/python3.12/site-packages/faster_whisper/audio.py
46: with av.open(input_file, mode="r", metadata_errors="ignore") as container:
+ venv/bin/python src/show_open.py
av_version 18.1.0
doc_has_metadata_errors True
kw_open=ok
plain_open=ok codec mp3float rate 24000 channels 1
+ cat > src/options.py << 'PY'
+ venv/bin/python src/options.py
vad_filter_default False
language_default None
ko_accepted True
kr_accepted False
+ venv/bin/python src/transcribe.py
[0.00 -> 1.12] 안녕하세요.
[1.84 -> 7.24] 이 음성은 AI News Note 2VB의 TTS로 만든 테스트 음성입니다.
[8.00 -> 10.92] 오늘은 2016년 10월 9일입니다.
language=ko
duration=11.736
TEXT=안녕하세요. 이 음성은 AI News Note 2VB의 TTS로 만든 테스트 음성입니다. 오늘은 2016년 10월 9일입니다.
transcribe_exit=0av 18.1.0으로 바꾼 뒤 같은 음성을 전사한 화면입니다. kw_open=ok와 transcribe_exit=0이 함께 찍혀 파일 열기와 전사 경로가 모두 통과했습니다. 입력 길이도 duration=11.736 그대로이니, 음성을 바꿔서 오류를 피한 것이 아니라 의존성 조합을 바꿔서 풀린 것입니다.
PyPI 1.2.1의 audio.py를 고치지 않고 av 패키지만 18.1.0으로 내리면 46행 호출이 통과하고, 한국어 전사도 transcribe_exit=0까지 갑니다. 대신 그 가상환경의 av는 18.1.0에 묶입니다. 19.0.0 노트가 말한 metadata_errors 제거는 18.1.0 독스트링에 반영되어 있지 않고, 그 인자도 그대로 남아 있습니다.
PyAV 19를 지키고 싶을 때: 업스트림 커밋과 실행 옵션 확인
다른 패키지 때문에 av 18.1.0으로 맞추기 어렵다면, 19.0.1을 두고 faster-whisper 쪽을 바꾸는 길이 있습니다. 점검 스크립트는 먼저 PyPI 1.2.1과 av 19.0.1로 되돌리고, 로그에는 - av==18.1.0, + av==19.0.1이 남습니다. 독스트링 검사의 doc_has_metadata_errors는 다시 False가 되고, decode_audio는 46행과 core.py 479행에서 같은 TypeError를 냅니다. decode_before_exit=1입니다.
uv pip install -p venv 'av==19.0.1'
venv/bin/python -c 'from faster_whisper.audio import decode_audio; decode_audio("audio/hello-ko.mp3")'
uv pip install -p venv --no-deps --reinstall 'faster-whisper @ git+https://github.com/SYSTRAN/faster-whisper.git@2ce7f9d7a9fbe315a5804a33bf7224d42e101174'커밋 설치 로그를 보면 버전 번호는 1.2.1 그대로이고 출처만 git 커밋으로 바뀝니다. importlib.metadata도 faster-whisper==1.2.1, av==19.0.1을 찍습니다. 설치된 audio.py에는 메이저 버전이 19보다 작을 때만 metadata_errors를 넘기도록 _AV_OPEN_KWARGS가 들어 있고, grep에 잡힌 줄은 18, 20, 21, 52입니다. 52행은 av.open(input_file, mode="r", **_AV_OPEN_KWARGS)입니다. 이 상태에서 같은 transcribe.py는 language=ko, duration=11.736, transcribe_exit=0으로 끝납니다.
grep -n -E 'metadata_errors|_AV_OPEN_KWARGS' venv/lib/python3.12/site-packages/faster_whisper/audio.py
venv/bin/python src/transcribe.py전체 로그에는 커밋 설치 전의 decode_before_exit=1과 설치 후의 transcribe_exit=0이 차례로 찍혀 있습니다. 패키지 표기는 계속 1.2.1인데, 설치 로그에는 고정된 git 커밋이 남고 호출부에는 _AV_OPEN_KWARGS가 나타납니다. 버전 출력만 보고 바뀐 게 없다고 판단하면 틀립니다. 설치 출처와 실제 오디오 호출부를 같이 봐야 합니다.
=== keep av 19.0.1 and install upstream commit ===
+ date --iso-8601=seconds
2026-10-14T13:40:19+09:00
+ uv pip uninstall -p venv faster-whisper || true
Using Python 3.12.15 environment at: venv
Uninstalled 1 package in 1ms
- faster-whisper==1.2.1
+ uv pip install -p venv 'faster-whisper==1.2.1'
Using Python 3.12.15 environment at: venv
⠋ Resolving dependencies... ⠙ Resolving dependencies... ⠋ Resolving dependencies... ⠙ Resolving dependencies... ⠙ faster-whisper==1.2.1 ⠙ ctranslate2==4.8.3 ⠙ huggingface-hub==2.2.0 ⠙ tokenizers==0.23.3 ⠙ onnxruntime==1.31.0 ⠙ av==18.1.0 ⠙ tqdm==4.70.1 ⠙ numpy==2.5.4 ⠙ pyyaml==6.0.3 ⠙ click==8.5.0 ⠙ filelock==4.1.1 ⠙ fsspec==2026.9.0 ⠙ hf-xet==1.7.0 ⠙ hf-xet==1.7.0 ⠙ httpx2==2.13.1 ⠙ httpcore2==2.13.1 ⠙ httpcore2==2.13.1 ⠙ packaging==26.3 Resolved 23 packages in 6ms
░░░░░░░░░░░░░░░░░░░░ [0/0] Installing wheels... ░░░░░░░░░░░░░░░░░░░░ [0/1] Installing wheels... ░░░░░░░░░░░░░░░░░░░░ [0/1] faster-whisper==1.2.1 ████████████████████ [1/1] faster-whisper==1.2.1 Installed 1 package in 3ms
+ faster-whisper==1.2.1
+ uv pip install -p venv 'av==19.0.1'
Using Python 3.12.15 environment at: venv
⠋ Resolving dependencies... ⠋ Resolving dependencies... ⠙ Resolving dependencies... ⠙ av==19.0.1 ⠙ Resolved 1 package in 1ms
Uninstalled 1 package in 18ms
░░░░░░░░░░░░░░░░░░░░ [0/0] Installing wheels... ░░░░░░░░░░░░░░░░░░░░ [0/1] Installing wheels... ░░░░░░░░░░░░░░░░░░░░ [0/1] av==19.0.1 ████████████████████ [1/1] av==19.0.1 Installed 1 package in 312ms
- av==18.1.0
+ av==19.0.1
+ venv/bin/python src/versions.py
faster-whisper==1.2.1
av==19.0.1
ctranslate2==4.8.3
onnxruntime==1.31.0
+ grep -n metadata_errors venv/lib/python3.12/site-packages/faster_whisper/audio.py
46: with av.open(input_file, mode="r", metadata_errors="ignore") as container:
+ venv/bin/python src/show_open.py
av_version 19.0.1
doc_has_metadata_errors False
kw_open=TypeError: open() got an unexpected keyword argument 'metadata_errors'
plain_open=ok codec mp3float rate 24000 channels 1
+ venv/bin/python -c 'from faster_whisper.audio import decode_audio; decode_audio("audio/hello-ko.mp3")'
Traceback (most recent call last):
File "<string>", line 1, in <module>
File "/home/user/whisper/run/venv/lib/python3.12/site-packages/faster_whisper/audio.py", line 46, in decode_audio
with av.open(input_file, mode="r", metadata_errors="ignore") as container:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "av/container/core.py", line 479, in av.container.core.open
TypeError: open() got an unexpected keyword argument 'metadata_errors'
decode_before_exit=1
+ uv pip install -p venv --no-deps --reinstall 'faster-whisper @ git+https://github.com/SYSTRAN/faster-whisper.git@2ce7f9d7a9fbe315a5804a33bf7224d42e101174'
Using Python 3.12.15 environment at: venv
⠋ Resolving dependencies... ⠋ Resolving dependencies... ⠙ Resolving dependencies... ⠹ Resolving dependencies... ⠸ Resolving dependencies... ⠼ Resolving dependencies... ⠴ Resolving dependencies... ⠴ faster-whisper==1.2.1 ⠴ Resolved 1 package in 915ms
⠋ Preparing packages... (0/0) ⠋ Preparing packages... (0/1) ⠙ Preparing packages... (0/1) ⠙ (1/1) Prepared 1 package in 7ms
Uninstalled 1 package in 0.72ms
░░░░░░░░░░░░░░░░░░░░ [0/0] Installing wheels... ░░░░░░░░░░░░░░░░░░░░ [0/1] Installing wheels... ░░░░░░░░░░░░░░░░░░░░ [0/1] faster-whisper==1.2.1 (from git+https://github.com/SYSTRAN/faster-whisper.git@2ce7f9d7a9fbe████████████████████ [1/1] faster-whisper==1.2.1 (from git+https://github.com/SYSTRAN/faster-whisper.git@2ce7f9d7a9fbeInstalled 1 package in 5ms
- faster-whisper==1.2.1
+ faster-whisper==1.2.1 (from git+https://github.com/SYSTRAN/faster-whisper.git@2ce7f9d7a9fbe315a5804a33bf7224d42e101174)
+ venv/bin/python src/versions.py
faster-whisper==1.2.1
av==19.0.1
ctranslate2==4.8.3
onnxruntime==1.31.0
+ grep -n -E 'metadata_errors|_AV_OPEN_KWARGS' venv/lib/python3.12/site-packages/faster_whisper/audio.py
18:# `metadata_errors` was removed in PyAV 19; pass it only for older versions
20:_AV_OPEN_KWARGS = (
21: {"metadata_errors": "ignore"} if int(av.__version__.split(".")[0]) < 19 else {}
52: with av.open(input_file, mode="r", **_AV_OPEN_KWARGS) as container:
+ venv/bin/python src/options.py
vad_filter_default False
language_default None
ko_accepted True
kr_accepted False
+ venv/bin/python src/transcribe.py
[0.00 -> 1.80] 안녕하세요.
[1.80 -> 4.52] 이 음성은 AI 뉴스 노트블로그에서
[4.52 -> 8.00] led-tts로 만든 테스트 음성입니다.
[8.00 -> 11.60] 오늘은 2016년 10월 9일입니다.
language=ko
duration=11.736
TEXT=안녕하세요. 이 음성은 AI 뉴스 노트블로그에서 led-tts로 만든 테스트 음성입니다. 오늘은 2016년 10월 9일입니다.
transcribe_exit=0
+ curl -sI source urls
+ curl -sI -o /dev/null -w '%{http_code} %{url_effective}\n' 'https://github.com/SYSTRAN/faster-whisper'
200 https://github.com/SYSTRAN/faster-whisper
+ curl -sI -o /dev/null -w '%{http_code} %{url_effective}\n' 'https://github.com/SYSTRAN/faster-whisper/issues/1589'
200 https://github.com/SYSTRAN/faster-whisper/issues/1589
+ curl -sI -o /dev/null -w '%{http_code} %{url_effective}\n' 'https://github.com/SYSTRAN/faster-whisper/blob/v1.2.1/faster_whisper/audio.py'
200 https://github.com/SYSTRAN/faster-whisper/blob/v1.2.1/faster_whisper/audio.py
+ curl -sI -o /dev/null -w '%{http_code} %{url_effective}\n' 'https://github.com/SYSTRAN/faster-whisper/commit/2ce7f9d7a9fbe315a5804a33bf7224d42e101174'
200 https://github.com/SYSTRAN/faster-whisper/commit/2ce7f9d7a9fbe315a5804a33bf7224d42e101174
+ curl -sI -o /dev/null -w '%{http_code} %{url_effective}\n' 'https://github.com/PyAV-Org/PyAV'
200 https://github.com/PyAV-Org/PyAV
+ curl -sI -o /dev/null -w '%{http_code} %{url_effective}\n' 'https://github.com/PyAV-Org/PyAV/releases/tag/v19.0.0'
200 https://github.com/PyAV-Org/PyAV/releases/tag/v19.0.0
+ curl -sI -o /dev/null -w '%{http_code} %{url_effective}\n' 'https://github.com/PyAV-Org/PyAV/releases/tag/v18.1.0'
200 https://github.com/PyAV-Org/PyAV/releases/tag/v18.1.0
+ curl -sL issue, release, compare summaries
issue_title PyAV open() does not accept metadata_errors argument
issue_state closed
issue_created 2026-10-02T09:56:27Z
issue_line TypeError: open() got an unexpected keyword argument 'metadata_errors'
issue_line TypeError: open() got an unexpected keyword argument 'metadata_errors'
issue_line `faster-whisper` should be able to open and decode the audio file without raising a `TypeError`.
issue_line python 3.14.8, windows.
issue_line package: av, version: 19.0.0
issue_line `av < 19`
pyav_release v19.0.0 2026-09-29T17:31:59Z
pyav_note - Drop support for Python 3.11. Binary wheels are now built for Python 3.12 and later.
pyav_note - Remove the `metadata_encoding` and `metadata_errors` arguments to `av.open`, and the matching attributes. Metadata is now always read and written as UTF-8 with `surrogateescape`, which is byte exact: a tag in another encoding survives as surrogates and is recovered per key with `value.encode("utf-8", "surrogateescape").decode("cp1251")`. Previously one encoding had to be chosen for a whole container, so a file mixing encodings across tags could not be represented at all.
compare_status ahead
compare_ahead_by 4
compare_total_commits 4
compare_commit cf42429f96 Remove "local_dir_use_symlinks" from download_model() (#1389)
compare_commit 2eeafe05de Update Silero-VAD weights to v6.2 (#1390)
compare_commit ed9a06cd89 Adds new VAD parameters (#1386)
compare_commit 2ce7f9d7a9 Adopt av.open usage according to PyAV 19.0.0 (#1495)커밋 적용 결과와 PyAV 릴리스 설명이 한 화면에 잡혀 있습니다. av 19.0.1을 유지하면서도 transcribe_exit=0이 나왔고, 제거된 인자에 대응하는 커밋 제목도 출력에 남았습니다. 운영 기록에 성공 여부만이 아니라 설치 출처까지 적어 둬야, 버전 문자열이 같은 PyPI 배포물과 헷갈리지 않습니다.
이 커밋 트리는 태그 v1.2.1보다 compare_ahead_by 4, compare_total_commits 4만큼 앞서 있습니다. 커밋 제목은 download_model()의 local_dir_use_symlinks 제거, Silero-VAD 가중치 v6.2, 새 VAD 파라미터, 그리고 Adopt av.open usage according to PyAV 19.0.0입니다. 오디오 인자만 고친 단일 파일 패치로 여기면 실제 설치물과 어긋납니다.
해결 스크립트가 PyPI 1.2.1에서 찍은 값과, 커밋 설치 뒤 점검 스크립트가 다시 찍은 값은 같습니다. vad_filter_default는 False, language_default는 None입니다. transcribe.py는 vad_filter를 넘기지 않고 language="ko"를 넘깁니다. 아래 검사 코드는 기본값과 허용 언어 코드를 함께 찍으니, 커밋을 바꾼 뒤에도 실행 옵션이 의도대로인지 확인하는 데 그대로 쓸 수 있습니다.
import inspect
from faster_whisper import WhisperModel
from faster_whisper.tokenizer import _LANGUAGE_CODES
sig = inspect.signature(WhisperModel.transcribe)
print("vad_filter_default", sig.parameters["vad_filter"].default)
print("language_default", sig.parameters["language"].default)
print("ko_accepted", "ko" in _LANGUAGE_CODES)
print("kr_accepted", "kr" in _LANGUAGE_CODES)허용 코드 튜플에서는 ko_accepted가 True이고 kr_accepted는 False입니다. 한국어 전사는 language="ko"로 호출하면 되고, 성공 출력의 language 필드도 ko입니다. PyAV 19.0.0 노트는 Python 3.11 지원을 끊고 바이너리 휠은 3.12부터 만든다고 적습니다. 이 글의 인터프리터는 Python 3.12.15이고, 그 위에서 av 19.0.1 휠이 동작했습니다.
이 길을 택하면 av 19.0.1을 지키면서 decode 경로의 TypeError가 사라지고 transcribe_exit=0까지 갑니다. 문제는 배포 버전 문자열이 PyPI 1.2.1과 똑같다는 것입니다. 둘을 가르는 표시는 설치 로그의 git URL과 audio.py의 _AV_OPEN_KWARGS뿐이고, 트리에는 VAD 관련 커밋 두 개와 download_model 변경도 같이 딸려 옵니다.
Whisper 헬스체크는 전사문이 나오는 데까지
실제 출력에서 PyAV 19.0.1은 metadata_errors를 거부했고, 대응 커밋은 메이저 버전에 따라 넘기는 인자를 나눴습니다. 서비스 헬스체크도 패키지 가져오기나 모델 생성에서 멈추지 말고, 짧은 음성을 열어 전사문을 받아 내는 경로까지 넣어야 합니다. plain_open=ok만 보고는 faster-whisper 내부의 decode_audio 호출이 성공한다고 말할 수 없기 때문입니다.
설정과 배포 기록에는 faster-whisper와 av의 고정 조합, 모델 경로, 설치 출처를 함께 적습니다. 이번 실행의 모델 경로 models/faster-whisper-tiny와 가상환경 venv를 기준으로 점검 대상을 맞추면, 엉뚱한 환경의 패키지를 들여다보는 일이 없습니다. 커밋 설치를 골랐다면 audio.py의 _AV_OPEN_KWARGS와 전사 결과를 확인하고, 다음 배포에서도 같은 조합이 복원되도록 의존성 고정 설정을 고쳐 둡니다.
PyAV를 내릴지, 커밋을 올릴지
세 조합 모두 같은 Debian 환경에서 돌렸습니다. 표에는 호출 인자 오류가 난 조합과 전사가 끝난 조합을 나란히 놓았습니다. 전사 성공은 language=ko와 transcribe_exit=0에 더해 실제 전사문까지 읽고 판단했습니다.
| 선택 | 맞춤 버전 | 이 실행의 결과 |
|---|---|---|
| PyPI 1.2.1과 av 19.0.1 | faster-whisper==1.2.1, av==19.0.1, audio.py 46행이 metadata_errors를 항상 전달 | kw_open TypeError, transcribe_exit=1, core.py 479행 |
| PyPI 1.2.1과 av 18.1.0 | av==18.1.0, 46행은 유지, 독스트링에 metadata_errors 있음 | kw_open=ok, language=ko, duration=11.736, transcribe_exit=0 |
| 커밋 2ce7f9d와 av 19.0.1 | 버전 표기는 1.2.1, 출처는 해당 git 커밋, av==19.0.1, _AV_OPEN_KWARGS | language=ko, duration=11.736, transcribe_exit=0 |
PyPI에 올린 1.2.1 파일을 그대로 두고 싶을 때는 av 18.1.0 고정을 권합니다. 이슈 1589의 workaround 문구가 av < 19이고, 이번 설치에서 그 조건을 만족하는 릴리스가 18.1.0이었습니다. 다른 의존성 때문에 av 19.0.1을 남겨 두어야 하는 경우에는 커밋 2ce7f9d7a9fbe315a5804a33bf7224d42e101174 설치를 권합니다. 설치 뒤에는 버전 번호와 함께 설치 로그의 git URL과 audio.py의 _AV_OPEN_KWARGS를 확인합니다.
한국어 음성을 넘길 때는 language="ko"를 쓰면 됩니다. 허용 코드 검사에서 ko는 들어 있고 kr은 들어 있지 않았습니다. 이번 Debian 환경에서는 device="cpu"와 compute_type="int8"으로 tiny 로컬 모델을 올리면, 위의 두 성공 경로 모두 11.736초 파일을 전사합니다.
출처는 2026-10-14에 HEAD로 확인했고 응답 코드는 200입니다. faster-whisper 저장소는 https://github.com/SYSTRAN/faster-whisper, 이슈 1589는 https://github.com/SYSTRAN/faster-whisper/issues/1589, 1.2.1의 audio.py는 https://github.com/SYSTRAN/faster-whisper/blob/v1.2.1/faster_whisper/audio.py, 설치한 커밋은 https://github.com/SYSTRAN/faster-whisper/commit/2ce7f9d7a9fbe315a5804a33bf7224d42e101174입니다. PyAV 저장소는 https://github.com/PyAV-Org/PyAV, 19.0.0 노트는 https://github.com/PyAV-Org/PyAV/releases/tag/v19.0.0, 18.1.0 태그는 https://github.com/PyAV-Org/PyAV/releases/tag/v18.1.0입니다.
실행 결과로 보면, 짧은 한국어 음성의 배치 전사는 PyPI faster-whisper 1.2.1과 av 18.1.0을 고정하고 CPU int8 설정과 tiny 로컬 모델로 시작하는 구성을 권합니다. av 19.0.1이 필요한 환경이라면 검증한 커밋을 고정하고, 배포할 때마다 오디오 열기와 전사 완료를 같이 점검합니다. 모델 파일과 의존성을 한 배포 단위로 묶어 두면 재설치한 뒤에도 같은 조건으로 복구하기 쉽습니다. 실시간 서비스라면 음성 길이와 처리 시간을 구분하고, 실제 요청의 지연과 동시 처리량을 재서 CPU 증설, GPU 사용, 비동기 작업 큐 도입을 판단해야 합니다. 이번에 전사한 11.736초는 입력 길이이지 실시간 처리 성능의 근거가 아니며, 이 구성은 의존성 호환성과 전사 성공을 확인한 조합으로만 씁니다.
