動画のマスキングを自動化するツール開発で、Windowsで詰まった3つの罠

動画のマスキング処理をローカルAIで自動化する試み

動画内の個人情報を隠すマスキング処理を手作業で行うのは大変です。しかし、機密情報が含まれる動画を外部のクラウドAIに送信するのはセキュリティ上のリスクがあります。そこで、外部サーバーを使わず、ローカルPC内だけで完結する自動マスキングツールを開発しました。Python、PaddleOCR、FFmpegを組み合わせた仕組みです。この記事では、このツールをWindows環境で構築する際に直面した3つの致命的なエラーと、その具体的な解決策を一次情報として共有します。

動画に写り込んだAPIキーをそのまま公開するとどうなりますか？

公開から数分以内にクローラーに検知され、不正利用されて高額な請求が発生するリスクがあります。そのため、自動検出による下処理と人手による最終確認を組み合わせた安全なワークフローが不可欠です。

外部APIを一切叩かないため、インターネットに接続されていない環境でも完全に動作します。企業の機密データや個人開発のデモ動画も安全に処理できます。

Windows環境の開発で実際に踏んだ3つのエラーと解決策

Windows環境特有の仕様やライブラリの互換性により、いくつかの深刻なエラーに遭遇しました。公式ドキュメントには載っていない、実践的なトラブルシューティングの記録です。

1. Python 3.14環境におけるPaddleOCRのクラッシュ

テスト環境に最新のPython 3.14を使用したところ、初回起動時にPaddleOCRの実行プロセスが強制終了しました。原因は、動作基盤であるPaddlePaddleのWindowsバイナリが、Python 3.13までしか正式対応していないためです。

エラー時にコマンドプロンプトが即座に閉じてログが読めないため、起動用の run.bat に一時停止（pause）処理を加えました。pip install -r requirements.txt が失敗したらその場で pause して止め、成功したときだけ streamlit run app.py へ進み、最後にもう一度 pause を置く。この3か所だけでエラー文が画面に残ります。

実行環境のPythonを3.13.x（64-bit）にダウングレードし、PaddleOCRのバージョンを安定版に固定することで解決しました。

2. 日本語フォルダ名によるFFmpegの文字化けと出力失敗

Windows環境では、フォルダ名に日本語が含まれていると、FFmpegがパスを正しく認識できずエラーになります。

対策として、動画の読み込みと一時レンダリングは英数字のみのシステム一時フォルダ（Temp）で行う仕様にしました。完成ファイルのみをPythonの shutil で目的のフォルダへコピーし、文字化けによる出力失敗を回避しています。

3. 初回起動時のStreamlitメール登録プロンプトによるハングアップ

パッケージを展開して初めて run.bat を実行した際、Streamlitがコンソール上でメールアドレスの登録を求め、処理が止まる問題が発生しました。バックグラウンド実行では入力待ちに気づけず、フリーズしたように見えます。

この挙動を防ぐため、起動ディレクトリに .streamlit/config.toml を自動生成して以下の設定を流し込みました。

[browser]
gatherUsageStats = false

[server]
headless = true

これにより初回の入力画面をスキップし、ダブルクリックだけでブラウザ画面が立ち上がるスムーズな挙動を実現しています。

同じ環境を手元で再現する具体手順

同じようなツールを自分で動かしたい場合、以下の手順で処理の流れを再現できます。

まずは、文字認識を行う「PaddleOCR」と、動画を制御する「FFmpeg」をインストールします。

pip install streamlit paddleocr paddlepaddle opencv-python ffmpeg-python

アプリ起動後は、検出漏れを防ぐために以下の推奨設定値で処理を開始します。

自動検出はあくまで補助的な位置づけです。公開前には必ず人手で最後まで動画を再生し、見落としがないか確認してください。

開発効率を最大化するためのAIエディタの使いこなし

ローカルツールを短期間で設計・実装する際、AIエディタのサポートは不可欠です。特にStreamlitのUI設計やFFmpegの複雑な引数調整は、AIにコードを生成させることで開発時間を大幅に短縮できます。

最新のAI開発ツールの特徴や、どれを選ぶべきかの基準については、こちらのCursor・Windsurf・Claude Codeの課金でつまずく3つの注意点でそれぞれの強みを詳しくレビューしています。

あわせて読みたいCursor・Windsurf・Claude Codeの課金でつまずく3つの注意点Cursor・Windsurf・Claude Codeの課金で迷っていませんか？本記事では、3大AIツールの料金プランや機能、Windows環境での注意点を比較…

/blog/ai-editors-comparison-2026/

また、外出先から自宅のハイスペックなWindowsマシンにアクセスして、動画のレンダリングやAIモデルの挙動テストをリモートで行いたい場合は、以下の外出先のスマホから自宅PCの作業を続ける方法。30秒で切れる問題も解決に実践的なネットワーク構築手順をまとめています。

あわせて読みたい外出先のスマホから自宅PCの作業を続ける方法。30秒で切れる問題も解決外出先のスマホから自宅のWindowsに入り、そのまま作業を続けるまでの手順です。接続が30秒で切れる原因と、その直し方まで実際に詰まった順に残しています。

/blog/iphone-pc-cooperation-devlog/

まとめと次にやること

まずは、手元のPython環境にPaddleOCRとFFmpegをインストールし、短いテスト動画を使って文字検出の挙動を確認することから始めてみてください。

ただ、Windows特有のエラーをすべて回避しながら、実用的な動画マスキングツール「ClipShield Local」をゼロから不具合なく組み上げるには、多くの時間と検証の手間がかかります。