Lua と FFmpeg で動画から ASCII アートを作成
Lua で動画の各フレームの明るさを文字に対応付け、その文字を描画して音声なしの ASCII アート動画にします。以下の例では、FFmpeg でデコードし、ImageMagick で文字を描画して、80 列のテキストグリッドと、毎秒 10 フレームの 640 × 360 の MP4 を生成します。
短い入力動画の選択
まず、ピクセルが正方形で、破損のない短い SDR 動画を用意します。顔、シルエット、コントラストの大きな形状は、小さな文字や複雑な背景よりも変換後に形を保ちやすくなります。この視覚効果はフレームを間引いて生成するため、音声、色、細部は失われ、元のすべてのフレームが保持されるわけではありません。
このワークフローは Linux 上の Bash でローカルに実行します。PNG フレーム、ASCII テキスト、描画済み PNG、最終動画を保存するため、見た目を調整する間は短いクリップを使用してください。フレームは順番に処理し、最初の失敗を検出した時点で停止します。
ツールの確認と作業ディレクトリの作成
Bash、Lua、FFmpeg と ffprobe、ImageMagick 7 の magick コマンド、読み取り可能な等幅フォントファイルが必要です。LuaRocks や Lua の画像ライブラリは不要です。ここで紹介するコマンドは、Lua 5.5.1、FFmpeg/ffprobe 9.0.1、ImageMagick 7.1.2-31、Liberation Mono で検証しました。また、Lua プログラムは Lua 5.4.8 で、ワークフローは FFmpeg/ffprobe 6.1.1 でも再実行しました。これは検証済みバージョンの一覧であり、その間のすべてのリリースや別の OS での検証を示すものではありません。Lua を新規にインストールする場合は、現行リリースを使用してください。Lua 5.4 は最終リリースに到達しています。
これらのツールは、Linux ディストリビューションまたは公式のダウンロードからインストールします。FFmpeg のビルドには libx264 エンコーダーが含まれている必要があります。また、ImageMagick は PNG とテキストの描画に対応している必要があります。先に進む前に、コマンドを確認してください。
lua -v && ffmpeg -version && ffprobe -version && magick -version
新しいディレクトリを作成し、作成に成功した場合のみそのディレクトリに移動します。ascii-demo がすでに存在する場合は、別の名前を選んでください。チュートリアルを進めるために既存のプロジェクトを削除しないでください。
mkdir -- ascii-demo && cd -- ascii-demo
クリップをこのディレクトリに input.mp4 としてコピーします。再現可能な入力から始める場合は、代わりに次のコマンドで 1.3 秒のテストパターンを作成できます。既存の input.mp4 は上書きしません。
ffmpeg -nostdin -v error -n -f lavfi -i "testsrc2=size=320x180:rate=10:duration=1.3" \
-c:v libx264 -threads 1 -pix_fmt yuv420p input.mp4
FFmpeg による動画フレームの抽出
単一フレームをプレビューするために、新しいフレーム列を抽出します。丸括弧により、シェルオプションの適用範囲をこのブロック内に限定します。mkdir は既存の frames ディレクトリを再利用しません。
(
set -e
mkdir -- frames
ffmpeg -nostdin -v error -xerror -n -i ./input.mp4 -map 0:v:0 \
-vf "fps=10,scale=640:-2,setsar=1" -threads 1 -filter_threads 1 \
-start_number 1 frames/frame_%08d.png
)
FFmpeg の fps フィルターは 10 FPS でサンプリングします。scale=640:-2 は入力の縦横比を保ちながら高さを偶数にし、setsar=1 は出力ピクセルを正方形として指定します。16:9 のクリップからは、frame_00000001.png、frame_00000002.png
という名前で順に 640 × 360 の PNG が生成されます。付属のテストクリップでは 13 フレームが生成されます。サンプリング時にはタイムスタンプがフレームグリッドに丸められるため、任意の入力動画の長さと出力の長さには、およそ 1 フレーム分の 0.1 秒の差が生じる場合があります。
Lua による単一 PNG の ASCII 変換
次のプログラム全体を ascii.lua として ascii-demo に保存します。PNG の情報を調べ、FFmpeg から拡大縮小済みの RGB フレームをひとつ取得し、想定するすべてのピクセルを受け取ったことを確認してからテキストを組み立てます。
-- ascii.lua
local chars = " .:-=+*#@" -- Sparse to dense: white glyphs on a black background.
local columns = 80
local cellRatio = 0.5 -- Approximate character width divided by line height.
local function shellQuote(value)
return "'" .. value:gsub("'", "'\\''") .. "'"
end
local function readCommand(command)
local pipe = assert(io.popen(command, "r"))
local data, readError = pipe:read("*a")
local ok, reason, status = pipe:close()
assert(data, readError)
assert(ok, string.format("Subprocess failed (%s %s)", reason, status))
return data
end
local function main()
assert(arg[1] and not arg[3], "Usage: lua ascii.lua <PNG> [output.txt]")
local input = arg[1]
if input:sub(1, 1) ~= "/" then input = "./" .. input end
assert(input:match("%.png$"), "Input must be a local .png file")
assert(arg[2] ~= arg[1], "Input and output must be different files")
local quoted = shellQuote(input)
local dimensions = readCommand(
"ffprobe -v error -f image2 -pattern_type none -select_streams v:0 " ..
"-show_entries stream=width,height -of csv=s=x:p=0 -i " .. quoted
)
local width, height = dimensions:match("^(%d+)x(%d+)%s*$")
width, height = tonumber(width), tonumber(height)
assert(width and height and width > 0 and height > 0, "Invalid PNG dimensions")
local rows = math.max(1, math.floor(height / width * columns * cellRatio + 0.5))
local pixels = readCommand(string.format(
"ffmpeg -nostdin -v error -xerror -err_detect explode -threads 1 " ..
"-f image2 -pattern_type none -i %s -map 0:v:0 " ..
"-vf scale=%d:%d -filter_threads 1 -frames:v 1 " ..
"-threads 1 -f rawvideo -pix_fmt rgb24 -", quoted, columns, rows
))
assert(#pixels == columns * rows * 3, "Incomplete or unexpected RGB pixel data")
local lines = {}
local position = 1
for y = 1, rows do
local line = {}
for x = 1, columns do
local r, g, b = pixels:byte(position, position + 2)
local brightness = 0.299 * r + 0.587 * g + 0.114 * b
local index = math.floor(brightness / 255 * (#chars - 1) + 0.5) + 1
line[x] = chars:sub(index, index)
position = position + 3
end
lines[y] = table.concat(line)
end
local text = table.concat(lines, "\n") .. "\n"
if arg[2] then
local output = assert(io.open(arg[2], "wb"))
local written, writeError = output:write(text)
local closed, closeError = output:close()
assert(written, writeError)
assert(closed, closeError)
else
assert(io.write(text))
assert(io.flush())
end
end
local ok, message = pcall(main)
if not ok then
io.stderr:write("Error: " .. tostring(message) .. "\n")
os.exit(1)
end
パイプを閉じることが重要です。Lua の file:close()は、io.popen で開いたハンドルについて、サブプロセスのステータスを返します。単にバイトを読み取れただけでは、FFmpeg の成功を確認したことにはなりません。このプログラムは出力の書き込みとクローズの両方も確認するため、ディレクトリの不在やディスクの空き容量不足を、保存成功として報告することはありません。
背景の暗いターミナルで最初のフレームをプレビューします。
lua ascii.lua frames/frame_00000001.png
保存する場合は、先に親ディレクトリを作成します。このコマンドは ascii_frames を再利用しませんが、Lua プログラム自体は、変換が成功して書き込みが始まると、保存先の既存テキストを上書きします。書き込みに失敗すると不完全なテキストファイルが残る場合があるため、利用する前に終了ステータスを確認してください。
mkdir -- ascii_frames && lua ascii.lua frames/frame_00000001.png ascii_frames/frame_00000001.txt
16:9 のフレームでは、80 文字の行が 23 行生成される想定です。黒いピクセルは空白に、白いピクセルは @ に対応し、中間の明るさはその間の文字に対応します。行数の計算では、文字の高さが幅より大きいことをおおまかに補正しています。フォントのメトリクスに基づくものではありません。
ASCII アート動画の作成
次のスクリプトを create_ascii_video.sh として、ascii.lua と同じ場所に保存します。元動画から新しいフレームを独自に抽出するため、プレビュー用ディレクトリは使用しません。入力パスと新しい出力ディレクトリを指定してください。既存の保存先は使用せず、失敗した場合は調査用に中間ファイルを保持します。生成動画のエンコード、フレーム数の確認、デコードが完了してから、ascii_video.mp4 を最終出力として配置します。
パスに % 文字を含まないローカルの出力ディレクトリを使用してください。FFmpeg は、シェルの引用符内でも画像シーケンスのパスに含まれる % を解釈します。空白や先頭のハイフンには対応しています。同時に実行するのはひとつだけにし、処理中は入力ファイルや中間ファイルを変更しないでください。
#!/usr/bin/env bash
set -euo pipefail
export LC_ALL=C
die() { printf 'Error: %s\n' "$*" >&2; exit 1; }
[[ $# -eq 2 ]] || die 'Usage: bash create_ascii_video.sh INPUT_VIDEO NEW_OUTPUT_DIRECTORY'
input=$1
run=$2
[[ $input = /* ]] || input="./$input"
[[ $run = /* ]] || run="./$run"
[[ $run != *%* ]] || die 'Output path must not contain %'
[[ -r $input && -f $input ]] || die 'Input video is not a readable file'
[[ -f ascii.lua ]] || die 'Run from the directory containing ascii.lua'
[[ ! -e $run && ! -L $run ]] || die 'Output directory already exists; choose a new name'
font=${FONT:-/usr/share/fonts/liberation/LiberationMono-Regular.ttf}
[[ -r $font && -f $font ]] || die 'Set FONT to a readable monospaced font file'
for tool in lua ffmpeg ffprobe magick; do
command -v "$tool" >/dev/null || die "Missing tool: $tool"
done
mkdir -- "$run"
mkdir -- "$run/frames" "$run/ascii_frames" "$run/ascii_images"
temporary="$run/ascii_video.part.mp4"
trap 'rm -f -- "$temporary"' EXIT
# A reported FFmpeg error is a failure even if that build returns zero.
run_ffmpeg() {
if ! ffmpeg -nostdin -v error -xerror "$@" 2>"$run/ffmpeg.log"; then
cat -- "$run/ffmpeg.log" >&2
die 'FFmpeg failed'
fi
[[ ! -s $run/ffmpeg.log ]] || { cat -- "$run/ffmpeg.log" >&2; die 'FFmpeg reported an error'; }
}
run_ffmpeg -n -threads 1 -i "$input" -map 0:v:0 \
-vf 'fps=10,scale=640:-2,setsar=1' -threads 1 -filter_threads 1 \
-start_number 1 "$run/frames/frame_%08d.png"
shopt -s nullglob
frames=("$run"/frames/frame_*.png)
[[ ${#frames[@]} -gt 0 ]] || die 'No video frames were extracted'
count=0
for frame in "${frames[@]}"; do
count=$((count + 1))
printf -v name 'frame_%08d' "$count"
[[ $frame = "$run/frames/$name.png" ]] || die 'Frame sequence has a gap'
text="$run/ascii_frames/$name.txt"
image="$run/ascii_images/$name.png"
lua ascii.lua "$frame" "$text"
# Strip only the display copy’s final newline to avoid an extra blank label row.
printf '%s' "$(< "$text")" | magick -background black -fill white \
-font "$font" -pointsize 12 label:@- -resize 640x360 \
-gravity center -extent 640x360 "$image"
printf 'Rendered frame %d/%d\n' "$count" "${#frames[@]}"
done
run_ffmpeg -n -framerate 10 -start_number 1 -start_number_range 1 \
-i "$run/ascii_images/frame_%08d.png" -c:v libx264 -threads 1 \
-pix_fmt yuv420p -crf 18 "$temporary"
decoded=$(ffprobe -v error -select_streams v:0 -count_frames \
-show_entries stream=nb_read_frames -of csv=p=0 "$temporary")
[[ $decoded = "$count" ]] || die 'Encoded frame count does not match extracted frames'
run_ffmpeg -threads 1 -i "$temporary" -map 0:v:0 -f null -
mv -- "$temporary" "$run/ascii_video.mp4"
printf 'Created %s with %d frames at 10 FPS\n' "$run/ascii_video.mp4" "$count"
FONT に、インストール済みの等幅フォントの絶対パスを設定します。上記のデフォルト値は、検証に使用した Linux 上の Liberation Mono のパスです。ディストリビューションによっては別の場所にあります。インストール済みフォントは、システムのフォントツールで探せます。プロポーショナルフォントではグリッドの位置がずれます。
FONT=/usr/share/fonts/liberation/LiberationMono-Regular.ttf \
bash create_ascii_video.sh input.mp4 ascii-run
動画プレーヤーで ascii-run/ascii_video.mp4 を開きます。付属のテストパターンの場合、出力は 13 フレームで、10 FPS で 1.3 秒間再生されます。H.264 動画ストリームをひとつ含み、音声は含みません。最初と最後の描画済みフレームは、それぞれ ascii-run/ascii_images/frame_00000001.png と
ascii-run/ascii_images/frame_00000013.png です。
ImageMagick の label: レンダラーは、整形済みのグリッドを自動折り返しなしで描画します。余白を追加する前にラベルのサイズを変更するため、縦長のグリッドもキャンバス内に収まります。ImageMagick が @- の読み取りを拒否する場合は、インストール環境のセキュリティポリシーがテキストの間接読み込みをブロックしています。グローバルポリシーをむやみに無効化せず、適切に設定したローカル環境を使用してください。
見た目の調整
columns は ascii.lua 内で変更し、表現する細部の量を調整します。列数を増やすと、固定サイズの動画キャンバスに収めたときの文字が小さくなります。被写体が引き伸ばされて見える場合は、cellRatio を、選択したフォントの文字幅を行の高さで割った値に調整してください。白い背景に黒い文字を表示する場合は、chars の順序を反転させ、レンダラーの背景色と塗りつぶし色も一緒に変更します。
コントラストが弱い場合は、抽出フィルターの eq=contrast=1.3 を
setsar=1 の後に追加し、新しいディレクトリを出力先にしてスクリプトを実行してみてください。これは見た目の調整であり、品質の向上を保証するものではありません。抽出時と再生時のフレームレートは同じにしてください。最後の -framerate だけを変更すると、再生速度が変わります。
変換失敗の原因調査
既存の出力ディレクトリは、前回の実行が失敗した場合も含め、意図的に拒否します。中間ファイルと ffmpeg.log を調べてから、新しいディレクトリ名で再試行してください。これにより、古いテキストや画像が残って新しい短いクリップを引き延ばすのを防ぎます。Lua で失敗すると、その後の正常なフレームによって失敗が見えなくなる前にループを停止します。エンコードまたは最終デコードが失敗した場合、最終出力の ascii_video.mp4 は配置されません。
これらの確認では、サブプロセスの失敗、RGB データの不足、テキスト書き込みの失敗、バッチ内の FFmpeg 処理で報告されたエラーを検出します。ただし、元動画に破損がなかったことを証明するものではありません。デコーダーは、エラーを報告せずに破損したメディアを復元する場合があります。抽出フレーム数に加え、入力と出力の終わり付近で、内容を見分けられるか確認してください。サンプリングしたフレーム列の最終動画の長さは、フレーム数を 10 で割った値です。元の録画の完全性を証明するものではありません。
フレームごとに外部ツールを起動して中間ファイルを書き込むため、この方法はリアルタイム再生よりも、短いクリエイティブなクリップに適しています。まずは読みやすいグリッドと数秒の映像から始め、最初と最後のフレームで意図した効果を確認してから、クリップを長くしてください。
