AI と一緒に、Pyxel 3 で動く音楽・動画プレーヤーを作りました。MP3 ファイルをドロップすると、Python と NumPy だけで書いたデコーダーで音にして鳴らします。動画も 1 本内蔵しています。
この記事は、その中身と、確かめて分かったことの記録です。
実際に動くものは、Code & Magic で公開しています:Custom Codec Player
この記事で伝えたいのは、次の 3 つです。
- MP3 は、Python と NumPy だけでも正しくデコードできる。 ffmpeg の出力と比べて、波形の相関は 0.99999998 でした。
- 速さは「実時間の約 11 倍」。 10 秒の曲を 0.89 秒でデコードできました(M5 Max の MacBook Pro)。Pyxel では、1 フレームに 80 ms ずつ少しずつデコードして、画面を止めません。
- 「動いている」と「正しい」は別。 内蔵動画の音声には、すべての音が最大音量に張り付く間違いが隠れていました。波形を数字で見て、初めて気づきました。
検証環境
- MacBook Pro(Apple M5 Max)、Python 3.15.2、NumPy 2.5.4、Pyxel 3.0.2
- 数値は上のパソコンで測ったものです。お使いのパソコンやブラウザでは変わります
- コードを書いたのは AI です。内蔵動画は Google の Gemini(有料プラン)で生成した動画です
1. 何を作ったか
- MP3:ファイルをウィンドウにドロップすると、デコードして鳴らします。MPEG-1 / 2 / 2.5 の Layer III、モノラルとステレオに対応しています。
- 内蔵動画:10 秒、160×120 ドット、12 コマ/秒。
- 操作:再生・一時停止、早送り・巻き戻し、音量、曲の切り替え。
-
ファイル:本体
main.py、デコーダーmp3dec.py(約 840 行)、MPEG の表mp3_tables.py、内蔵動画の絵sheet.pngと音audio_data.py。
2. MP3 デコードの流れ
MP3 のデコードは、次の順に進みます。mp3dec.py では、おおむね段階ごとに関数が分かれています。
| 順 | 処理 | 中身 |
|---|---|---|
| 1 | フレームの頭を読む | 同期ワード、ビットレート、サンプリング周波数、ステレオの形式 |
| 2 | サイド情報 | 2 つの「グラニュール」(576 サンプルずつ)の設定 |
| 3 | ビット貯金 | 前のフレームの余りのデータを足す(最大 511 バイト) |
| 4 | スケールファクター | 周波数の帯ごとの音量 |
| 5 | ハフマン復号 | 576 個の周波数の値を取り出す |
| 6 | 逆量子化 | 値を 4/3 乗して、帯ごとの音量を掛ける |
| 7 | ステレオ | M/S ステレオ(和と差から左右へ)、インテンシティステレオ |
| 8 | 並べ替えとエイリアス除去 | 短いブロックの並べ替え、帯の境目のにじみを消す |
| 9 | 逆 MDCT | 周波数 → 時間(18 点または 6 点 × 3)、前のグラニュールと重ねて足す |
| 10 | 合成フィルター | 32 の帯を 1 本の音に戻す(多相フィルターバンク) |
NumPy の使いどころ
速さの鍵は、同じ計算をまとめて行うことです。
たとえば合成フィルターの前の DCT では、32 の帯 × 18 サンプルを (32, 18) の配列にして、18 サンプル分を 1 回の配列の計算で処理します。Python のループは 32 の帯の分だけで済みます。
b2d = buf2[ch].reshape(32, 18) # 576 個の値を 32 帯 × 18 サンプルに
antialias(b2d, aa_bands) # 帯の境目ごとに、18 サンプルまとめて
imdct_gr(b2d, overlap, ...) # 逆 MDCT も帯ごとに、まとめて
一方、ハフマン復号は 1 ビットずつ読み進めるしかないので、Python のループのままです。ここが一番時間のかかる所です。
表とコードの出どころ
ハフマン表、帯の幅、窓関数などの数値の表は、MPEG の規格で決まった定数です。これらは minimp3(CC0、パブリックドメイン相当)から写しています。
コードの流れも minimp3 に近い作りです(DCT の手順や定数がそのまま対応しています)。minimp3 は CC0 なので、写すことにも公開することにも問題はありません。ここでは正確に「minimp3 を参考に、NumPy 向けに書き直したもの」と書いておきます。
3. 正しくデコードできているか
ffmpeg で作った 10 秒の MP3(440 Hz の正弦波、ステレオ、128 kbps)を、このデコーダーと ffmpeg の両方でデコードして比べました。
| 比べたもの | 結果 |
|---|---|
| 波形の相関 | 0.99999998(ずらして一番合う所で) |
| ずれ | 104 サンプル |
| 長さ | このデコーダー 887,040 個、ffmpeg 882,000 個(左右合わせて) |
| 出力の形 | このデコーダーは −1〜1 の float、ffmpeg は 16 ビット整数 |
波形はほぼ完全に一致しました。
長さとずれの違いは、MP3 の先頭と末尾にある「エンコーダーの遅れ」と「詰め物」によるものだと考えています。ffmpeg はファイルに書かれた情報を見てこれを取り除きますが、このデコーダーは取り除いていません。曲のつなぎ目(ギャップレス再生)が要らなければ、聞いて分かる差ではありません。
4. 速さ
| 測ったもの | 結果 |
|---|---|
| 10 秒の MP3(ステレオ、128 kbps)のデコード | 0.89 秒(実時間の約 11 倍の速さ) |
1 曲を一気にデコードすると、その間は画面が止まります。そこで Pyxel では、デコードを「1 フレームずつ」に分けました。
def step_decode(self):
t_end = time.perf_counter() + 0.08 # このフレームで使ってよいのは 80 ms まで
while time.perf_counter() < t_end:
pcm, sr, nch, frac = next(self.dec_iter) # MP3 の 1 フレーム分(1,152 サンプル)
self.dec_chunks.append(pcm)
デコーダーをジェネレーター(yield で 1 フレームずつ返す関数)にしておくと、こうした分け方が簡単にできます。frac はどこまで進んだかの割合で、進み具合の表示に使います。
ブラウザ(Pyodide)では Python がパソコンより遅くなるので、デコードにはもっと時間がかかるはずです。ブラウザでの速さはまだ測っていません。
5. Pyxel で鳴らす
デコードした音は、22,050 Hz のモノラルにそろえて WAV ファイルに書き、Pyxel 3 の Sound.pcm() で読み込んで鳴らします。
音量の付け方が少し変わっています。同じ音を、いくつのチャンネルで同時に鳴らすかで音量を決めています。8 段階の音量なら、最大 8 チャンネルで同じ音を重ねて鳴らします。
def play_sound(self, sec):
for ch in range(8):
pyxel.stop(ch)
for ch in range(self.volume): # 音量 = 重ねるチャンネルの数
pyxel.play(ch, self.snd(), sec=sec)
sec= で途中から鳴らせるので、早送りと巻き戻しもこれで実現しています。
6. 内蔵動画は「MP4」ではない
内蔵動画は、MP4(H.264 など)のデコーダーで再生しているわけではありません。中身は、この道具のための簡単な独自形式です。
-
映像:160×120 の絵 120 枚を、横 15 × 縦 8 に並べた 1 枚の PNG(2400×960、約 890 KB)。色は 256 色のパレットにそろえています。再生中は、時刻からコマの番号を出して、その部分を
pyxel.blt()で切り出して描くだけです。 - 音声:4 ビットの IMA ADPCM(22,050 Hz、モノラル、110,544 バイト)。base85 の文字列にしてコードに埋め込んでいます。
パラパラ漫画と同じ仕組みです。Python で H.264 をデコードするのは重すぎるので、短い動画ならこの形が現実的だと思います。
7. 落とし穴:音声がすべて最大音量に張り付いていた
記事を書くために内蔵動画の音声を数字で調べたところ、デコードした音のすべてのサンプルが +1 か −1 に張り付いていました(図の上)。
原因は、ADPCM のデコードの単位の取り違えでした。
- IMA ADPCM の「1 歩の大きさ」の表は、16 ビット整数(−32,768〜32,767)の単位で書かれています。いちばん小さい 1 歩は 7 です。
- ところがデコーダーは、音を −1〜1 の float で持っていました。そこに 7 や 8 を足すので、1 回足しただけで範囲の外に出て、端に張り付きます。
整数の単位のまま計算し、最後に 32,768 で割るように直すと、ちゃんとした波形になりました(図の下)。
# 直したもの(整数のまま計算する)
step = STEP[index]
diff = step >> 3
if code & 4: diff += step
if code & 2: diff += step >> 1
if code & 1: diff += step >> 2
pred = pred - diff if code & 8 else pred + diff
pred = max(-32768, min(32767, pred))
out[i] = pred / 32768
音は鳴っていたので、「動いている」ように見えていました。でも実際は、ひどく割れた音でした。耳で聞くだけでなく、波形を数字で確かめることの大切さを改めて感じました。
この修正は、記事のために別の場所で試したものです。配布しているプレーヤーには、まだ入れていません。
8. 確かめていないこと
- ブラウザ(Code & Magic)での速さ。この記事の数値は、すべて Mac で測ったものです。
- いろいろな MP3 での動き。テストしたのは 1 種類(440 Hz の正弦波、ステレオ、128 kbps)だけです。可変ビットレート、モノラル、MPEG-2 / 2.5、インテンシティステレオの MP3 は試していません。
- ADPCM の修正を入れたプレーヤーでの、実際の聞こえ方。
まとめ
- Python と NumPy だけの MP3 デコーダーでも、ffmpeg とほぼ同じ波形が出て、実時間の約 11 倍の速さでデコードできました。
- Pyxel では、デコーダーをジェネレーターにして 1 フレーム 80 ms ずつ進めると、画面を止めずにデコードできます。
- 動画は MP4 ではなく、PNG のパラパラ漫画と ADPCM の独自形式です。
- 「音が鳴っている」ことは「正しい」ことの証明になりません。波形を数字で確かめて、内蔵動画の音声の間違いを見つけました。
ライセンス
- Pyxel:Takashi Kitao(MIT License)https://github.com/kitao/pyxel
- minimp3:lieff(CC0)https://github.com/lieff/minimp3 。MPEG の表とデコードの流れを参考にしています
- 内蔵動画:Google の Gemini(有料プラン)で生成

