Go による音声波形の生成:ステップ別ガイド
Go から FFmpeg を実行し、既存の録音から背景が透明な波形 PNG を作成します。Go は入力を検証し、FFmpeg が報告したエラーがあれば出力を拒否します。既存のファイルを置き換えずに画像を確定します。音声のデコードと波形の描画は FFmpeg が行うため、サードパーティーの Go パッケージは不要です。
前提条件
メンテナンスが継続されている Go リリースと、PNG エンコーダーおよび
showwavespic フィルターを備えた FFmpeg を使用します。この例は Linux 上の Go 1.26.8 と FFmpeg 9.0.1 でテスト済みです。後述の検証手順には ffprobe も必要です。対応するデコーダーがあれば、MP3、PCM WAV、Ogg 内の Vorbis、FLAC を扱えます。このコマンドラインツールは、信頼できる短いローカル録音を対象としています。
Go 環境のセットアップ
Go は公式手順に従い、FFmpeg は FFmpeg のダウンロードページからインストールします。以下のコマンドは Bash を使用します。プロジェクトを作成する前に、ツールを確認します。
go version && ffmpeg -version && ffprobe -version
新しいモジュールを作成します。サブシェルを使用するため、実行後も元の親ディレクトリに留まります。また、GOWORK=off により、上位の Go ワークスペースから分離します。
(
mkdir waveform-generator &&
cd waveform-generator &&
GOWORK=off go mod init waveform-generator &&
GOWORK=off go mod edit -go=1.22
)
セットアップに失敗した場合は、ここで中止してください。既存の waveform-generator ディレクトリは変更されません。別の新しい親ディレクトリを選んでください。以降のコマンドも、その親ディレクトリで実行します。
基本的な波形生成
以下の完全なプログラムを waveform-generator/main.go として保存します。最初の音声トラックのチャンネルをモノラルにミックスして描画します。小さなライターが FFmpeg の診断メッセージをターミナルに転送し、ログをメモリに蓄積せずに、メッセージが出力されたかどうかを記録します。
package main
import (
"context"
"flag"
"fmt"
"image/png"
"io"
"os"
"os/exec"
"os/signal"
"path/filepath"
"time"
)
type errorOutput struct {
reported bool
}
func (output *errorOutput) Write(data []byte) (int, error) {
if len(data) > 0 {
output.reported = true
}
return os.Stderr.Write(data)
}
func generateWaveform(ctx context.Context, input, output string, width, height int) error {
if width < 16 || width > 4096 || height < 16 || height > 1024 {
return fmt.Errorf("width must be 16–4096 and height 16–1024")
}
input, err := filepath.Abs(input)
if err != nil {
return err
}
info, err := os.Stat(input)
if err != nil {
return err
}
if !info.Mode().IsRegular() || info.Size() == 0 || info.Size() > 100*1024*1024 {
return fmt.Errorf("input must be a nonempty regular file of at most 100 MiB")
}
temporary, err := os.CreateTemp(filepath.Dir(output), ".waveform-*.png")
if err != nil {
return err
}
defer os.Remove(temporary.Name())
defer temporary.Close()
filter := fmt.Sprintf("[0:a:0]aformat=channel_layouts=mono,showwavespic=s=%dx%d:colors=0x167d9a:scale=sqrt:filter=peak[v]", width, height)
command := exec.CommandContext(ctx, "ffmpeg", "-hide_banner", "-loglevel", "error",
"-nostdin", "-protocol_whitelist", "file,pipe", "-i", input,
"-filter_complex", filter, "-map", "[v]", "-frames:v", "1",
"-c:v", "png", "-f", "image2pipe", "pipe:1")
diagnostics := &errorOutput{}
command.Stdout = temporary
command.Stderr = diagnostics
command.WaitDelay = 5 * time.Second
if err := command.Run(); err != nil {
return fmt.Errorf("render waveform: %w", err)
}
// FFmpeg can recover from a decoding error and still exit successfully.
if diagnostics.reported {
return fmt.Errorf("FFmpeg reported an error; waveform not published")
}
if err := ctx.Err(); err != nil {
return err
}
if _, err := temporary.Seek(0, io.SeekStart); err != nil {
return err
}
image, err := png.Decode(temporary)
if err != nil {
return fmt.Errorf("invalid waveform PNG: %w", err)
}
if image.Bounds().Dx() != width || image.Bounds().Dy() != height {
return fmt.Errorf("unexpected waveform dimensions")
}
if err := temporary.Close(); err != nil {
return err
}
// Linking publishes the complete file without replacing a concurrent writer's output.
if err := os.Link(temporary.Name(), output); err != nil {
return fmt.Errorf("publish waveform (destination must be new): %w", err)
}
return nil
}
func run() error {
width := flag.Int("width", 1024, "image width in pixels")
height := flag.Int("height", 256, "image height in pixels")
flag.Parse()
if flag.NArg() != 2 {
return fmt.Errorf("usage: waveform-generator [-width 1024] [-height 256] input.wav output.png")
}
interrupted, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()
ctx, cancel := context.WithTimeout(interrupted, 2*time.Minute)
defer cancel()
return generateWaveform(ctx, flag.Arg(0), flag.Arg(1), *width, *height)
}
func main() {
if err := run(); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
fmt.Println("Waveform saved")
}
所有している音声ファイルを waveform-generator/input.wav にコピーし、次を実行します。
(cd waveform-generator && GOWORK=off go run . input.wav waveform.png)
成功すると、コマンドは Waveform saved と表示します。waveform-generator/waveform.png を画像ビューアーで開いてください。画像は 1024 × 256 ピクセルで、背景は透明です。時間は左から右へ進みます。各列はサンプルの振幅の大きさを要約し、列が高いほどピークが大きいことを示します。平方根スケールにより、音の小さい区間も見やすくなります。これは振幅の概要であり、符号付きサンプルの波形や、知覚されるラウドネスの測定値ではありません。
高度な機能
大きなファイルのストリーミング
Go は PNG を直接ディスクに書き込みますが、showwavespic は画像を描画する前にデコード済みの音声フレームをキューに蓄積します。100 MiB の制限は入力ファイルに適用されます。コンテキストの二分間の期限は FFmpeg に適用され、プロセスの I/O の後処理には最大五秒が追加で認められます。Go のコンパイルはこの期限に含まれません。どちらの制限も、デコード済みデータのメモリ使用量を制限するものではありません。録音は短く保ち、同時実行数を抑えてください。長い録音には、サンプルを逐次集計するアルゴリズムを使用してください。
色とスタイルのカスタマイズ
別の波形色を選ぶには、フィルター内の固定値 colors=0x167d9a を変更します。画像サイズを変更するには、値が検証される幅と高さのフラグを使用します。
(cd waveform-generator && GOWORK=off go run . -width 800 -height 200 input.wav compact-waveform.png)
モノラルへのミックスはコンパクトなプレビューに適していますが、逆位相のステレオ信号は打ち消し合うことがあります。チャンネルを個別に確認するには、フィルター文字列から aformat=channel_layouts=mono, を削除し、split_channels=1 を showwavespic のオプションに追加します。編集したプログラムを保存し、再実行時は新しい出力ファイル名を使用してください。各チャンネルがそれぞれ独立した水平の帯に描画されます。
エラー処理と検証
FFmpeg はデコードエラーから回復し、有効な PNG を生成したうえで 0 を返すことがあります。error ログレベルには回復可能なエラーも含まれるため、このプログラムは出力を確定する前に、プロセスの失敗と、そのレベルの診断メッセージのいずれもエラーとして扱います。たとえば、最後のサンプルの途中で切り詰められた PCM WAV は、不完全な波形を生成して成功と報告するのではなく、失敗しなければなりません。
この方針で録音の完全性が証明されるわけではありません。警告は抑制され、デコーダーがエラーを出さずに破損を隠すこともあります。完全性が重要な場合は、録音の長さが想定どおりか確認し、実際に聴いてください。ファイル拡張子、有効な PNG、終了ステータス 0 のいずれも、それだけでは入力の完全性を証明できません。
音声トラックの欠落、キャンセル、無効な PNG 出力も、出力の確定を妨げます。一時ファイルは、失敗した場合も含め、関数が戻る際に削除されます。
FFmpeg が Too few samples を報告した場合は、幅を小さくしてください。このフィルターには、列ごとに少なくとも一つのデコード済みサンプルが必要です。幅は 16~4096 ピクセル、高さは 16~1024 ピクセルの範囲内にする必要があります。
出力先ディレクトリは事前に存在し、ハードリンクをサポートしている必要があります。エンコード中に作成されたものも含め、既存の出力は保持されます。実行ごとに新しいファイル名を使用してください。
テスト
短い合成トーンを生成し、波形を描画します。
(
cd waveform-generator &&
ffmpeg -hide_banner -loglevel error -nostdin -n -f lavfi -i "sine=frequency=440:duration=2" -c:a pcm_s16le tone.wav &&
GOWORK=off go run . tone.wav tone.png &&
ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,width,height -of json tone.png
)
プローブでは、幅 1024、高さ 256 の PNG と識別されるはずです。waveform-generator/tone.png も開いてください。画像全体にわたり、高さが等しいピークの帯が描画されているはずです。空のファイル、音声ではないファイル、既存の出力先を指定した再実行は、既存のファイルを置き換えることなく失敗しなければなりません。この手順を繰り返すときは、tone.wav と tone.png の両方に新しい名前を使用してください。
コマンドの再利用
元の録音はプレビューと一緒に保存し、無音区間やステレオのミックスを、実際に聞こえる音と比較できるようにしてください。この関数のコンテキストを使えば、ローカルのジョブランナーから処理をキャンセルすることもできます。ただし、これはアップロードサーバーではありません。マネージド処理については、Transloadit の音声サービスでサポートされているワークフローを参照してください。
