Windows 11 x64 でローカル動画を解析し、利用者が選択した補正だけを実行する Python アプリです。入力動画や診断情報をクラウドへ送信しません。
ffprobeによる入力解析と、利用可能な補正の提案- 11 組込み段階: デインターレース、手ぶれ補正、フリッカー除去、ノイズ除去、 デバンディング、色補正、シャープ化、アップスケール、フレーム補間、粒状感調整、 最終エンコード
- 任意の外部能力: Real-ESRGAN、RIFE、CodeFormer 顔復元
- GUI と CLI の同じ能力診断、明示的な外部バイナリ許可ルート、SHA-256 検証
CodeFormer は外部環境でのみ動く任意の顔復元段階です。そのため公開表示は
「11 組込み段階 + 任意の顔復元1段階」とし、単純な「12段」とは表示しません。
正本は src/video_enhance_lite/stages.py の STAGE_REGISTRY です。
リポジトリ名と CLI 名は video-enhance-lite、Python package 名は
video_enhance_lite です。
- Windows 11 x64
- Python 3.11〜3.13(package metadata:
>=3.11,<3.14) - GPU は必須ではありませんが、Real-ESRGAN/RIFE は Vulkan 対応環境が必要です
FFmpeg、Real-ESRGAN、RIFE、CodeFormer、モデル、サンプルメディアは配布物に 同梱しません。外部エンジンは各公式配布元から利用者が取得してください。
ソースを任意の読み取り可能な場所へ展開し、プロジェクトルートで実行します。
cd <project-root>
install-enhance.batインストーラーは次の場所にユーザー専用 venv を作り、現在の checkout と install
receipt を結び付けます。任意の pythonw.exe へは fallback しません。
依存関係はWindows x64専用の requirements-lock-win-x64.txt に固定し、wheelの
SHA-256を検証します。source distributionへのfallbackとinstaller実行時の依存再解決は行いません。
事前取得した完全なwheel集合でオフライン検証する場合は、VIDEO_ENHANCE_WHEELHOUSEを
対象Python版のwheelhouseへ設定してからinstallerを実行します。
%LOCALAPPDATA%\video-enhance-lite\venv\
%LOCALAPPDATA%\video-enhance-lite\install-root.txt
外部エンジンが未導入でも package の導入と GUI 起動は可能です。導入後に診断を 確認してください。
<project-root>\video-enhance-lite.bat
<venv-python> -m video_enhance_lite --self-check設定ファイルの既定場所は次です。
%LOCALAPPDATA%\video-enhance-lite\config\enhance-binaries.json
サンプルは .local/enhance-binaries.example.json にあります。これは説明用の
プレースホルダーであり、そのまま実行できる設定ではありません。実設定は source
tree の .local ではなく、ユーザー領域へ置きます。
まだ実設定がない場合は、PowerShell 7でプロジェクトルートから次を実行します。
既に enhance-binaries.json がある場合はコピーせず、既存JSONへ必要な項目だけを
追加してください。
$configDir = Join-Path $env:LOCALAPPDATA 'video-enhance-lite\config'
$configPath = Join-Path $configDir 'enhance-binaries.json'
New-Item -Path $configDir -ItemType Directory -Force | Out-Null
if (Test-Path -LiteralPath $configPath) {
Write-Host "既存設定を編集してください: $configPath"
} else {
Copy-Item -LiteralPath '.local\enhance-binaries.example.json' -Destination $configPath
}コピー後、<ffmpeg-root> などのプレースホルダーを、各PCで実際に配置した
ディレクトリへ置換します。JSON内のWindowsパスでは \ を \\ と記述します。
allowed_binary_roots には実行ファイルを含むディレクトリを能力ごとに明示します。
expected_sha256 を設定した能力はハッシュ不一致時に停止します。環境変数で一時的に
上書きする場合は VIDEO_ENHANCE_FFMPEG_ROOTS、VIDEO_ENHANCE_FFPROBE_ROOTS、
VIDEO_ENHANCE_REALESRGAN_ROOTS、VIDEO_ENHANCE_RIFE_ROOTS、
VIDEO_ENHANCE_EXPECTED_SHA256_JSON を使います。
解決順序は明示設定、許可ルート、PATH です。PATH で発見できても許可ルート外なら 拒否します。symlink/junction を含む経路、通常ファイルでない実体、期待名でない 実行ファイルも拒否します。
各実行ファイルのSHA-256はPowerShell 7で確認できます。
Get-FileHash -LiteralPath '<ffmpeg-root>\ffmpeg.exe' -Algorithm SHA256
Get-FileHash -LiteralPath '<ffmpeg-root>\ffprobe.exe' -Algorithm SHA256
Get-FileHash -LiteralPath '<realesrgan-root>\realesrgan-ncnn-vulkan.exe' -Algorithm SHA256
Get-FileHash -LiteralPath '<rife-root>\rife-ncnn-vulkan.exe' -Algorithm SHA256得られた値を小文字または大文字の16進数で expected_sha256 の対応する配列へ記載
します。ローカルで計算したハッシュは以後の改変検出には使えますが、最初から正規
配布物だったことは証明しません。公式配布元、対象バージョン、公式チェックサムが
提供されている場合は、それらを先に照合してください。
CodeFormerは allowed_binary_roots ではなく、repo、実行に使うPython、次の3モデルを
それぞれ設定します。統合形式は .local/enhance-binaries.example.json、詳細は
MIGRATE-CODEFORMER.md を参照してください。
roots.codeformer-local:inference_codeformer.pyがあるCodeFormer repoexecutables.codeformer-python: CodeFormer依存を導入した環境のpython.exemodels.codeformer:weights\CodeFormer\codeformer.pthmodels.facelib_detection:weights\facelib\detection_Resnet50_Final.pthmodels.facelib_parsing:weights\facelib\parsing_parsenet.pth
GPUを使う場合は、設定するPython環境でCUDAが利用できることも確認します。
& '<codeformer-python>' -c "import torch, cv2, basicsr, facelib; print(torch.cuda.is_available())"設定後はself-checkを実行します。
& "$env:LOCALAPPDATA\video-enhance-lite\venv\Scripts\python.exe" `
-m video_enhance_lite --self-check使用する能力が available になったことを確認してください。misconfigured の場合は
表示された解決先、許可ルート、ハッシュ、モデル配置を見直します。GUIを開いたまま
設定を変更した場合は、「環境診断」を再実行するかGUIを再起動します。
<venv-python> -m video_enhance_lite --self-check
<venv-python> -m video_enhance_lite <input-video> --analyze-only
<venv-python> -m video_enhance_lite <input-video> -o <output-dir>
<venv-python> -m video_enhance_lite <input-video> --auto --disable interpolate
出力先を省略した場合は %USERPROFILE%\Videos\video-enhance-lite\ を使います。
一時ファイルは %LOCALAPPDATA%\video-enhance-lite\temp\、または
VIDEO_ENHANCE_TEMP_ROOT/--temp-root で明示した場所です。ソースフォルダの親へ
暗黙に出力しません。
出力フォルダは処理開始前に作成し、書き込み可能か確認します。CLIの入力には相対パスも 指定できます。解析・解像度表示・拡大判定では、回転情報を反映した映像の幅と高さを使います。
最終ファイルは同じフォルダの <名前>.partial-<識別子>.mp4 へ書き出し、完了後に正式な
名前へ移します。失敗・キャンセル時は途中のファイルを削除するため、正式な名前には完成した
ファイルだけが残ります。処理中に同じ名前のファイルができた場合は上書きせず、~(1) などを
付けた名前で保存し、実際の保存先を表示します。完成後の移動だけが失敗した場合は、
完成したファイルを .partial- の名前のまま残し、その場所をエラーに表示します。
色補正・露出補正は、解析結果に応じて明るさ(最大±0.15)、コントラスト、彩度 (最大1.25倍)を控えめに調整します。通常の露出の白黒素材には彩度補正を推奨しません。 白飛び・黒潰れで失われた細部を復元する機能ではありません。
入力ストリームは処理前に全件検査します。出力 MP4 には、処理済み video と、入力順の
全 audio(aac / ac3 / eac3 / alac / mp3)、全 mov_text subtitle、global・
stream metadata、language、disposition を無変換で保持します。attachment、data、追加
video・cover art、image subtitle、上記以外の audio/subtitle codec がある入力は、silent
drop や暗黙 transcode を行わず、stream index と codec を表示して処理開始前に停止します。
解析とチャンク分割には映像ストリームの長さを使い、映像より長い音声・字幕の末尾は 最終結合で保持します。映像の長さがメタデータにない場合は、映像パケットの時刻を 走査して求めるため、解析に追加の読み取り時間がかかります。
解析中の ffprobe / ffmpeg は1回あたり120秒で打ち切ります(映像パケットの走査は、 毎秒 10 MiB の読み取り速度を見込んだ時間まで待ちます)。壊れたファイルや応答しない ドライブでは、止まり続けずにエラーで終了します。GUI のキャンセルや Ctrl+C では 実行中のプロセスをすぐに終了します。
映像と音声・字幕の開始時刻がずれている入力(音声が映像より先に始まる録画など)は、
そのずれを出力でも保ち、映像の先頭・末尾のフレームを落としません。MP4/MOV、
Matroska、FLV、MPEG-TS(.ts / .mts / .m2ts)で確認しています。
フレームレートは解析時にCFR、VFR suspected、unknownへ分類します。VFR suspectedは
nominal r_frame_rateへ明示CFR normalizationしてからPNGへ抽出し、全チャンクへ同じfpsと
global frame budgetを適用します。frame duplication/dropを伴う可能性はCLI/GUIで開始前に
表示します。unknownは推測で処理せずframerate_preflightで停止しますが、
--analyze-onlyによる診断表示は利用できます。
短尺動画などで解析用の最終sample時刻がlast decodable frameを越えた場合は、最終sample だけを警告付きで省き、それまでのsampleで解析を継続します。中間sampleの欠落、FFmpegの 失敗、全sampleを取得できない場合は、破損やmetadata不整合を隠さないため従来どおり停止します。
GUI の「環境診断」ボタンまたは --self-check は、Analyze、Encode/Decode、
Upscale、Interpolate、Face restore、Stabilize を個別に available、
unavailable、misconfigured、unsupported と表示します。不要な任意エンジンの
不足は、選択した処理の開始を妨げません。
- 外部バイナリの自動ダウンロード、クラウド API、認証トークンを使用しません
- 実行ファイルは許可ルート、通常ファイル、reparse point、期待名、任意の SHA-256 を確認してから実行します
- 設定、temp、出力、venv は公開候補から分離します
- ログを共有する前に、ユーザー名、入力動画名、ローカルパスを確認してください
- 脆弱性報告は
SECURITY.mdを参照してください
自動アンインストーラーはありません。アプリを終了してから、展開したソース一式と
%LOCALAPPDATA%\video-enhance-lite\venv\ を削除してください。設定、ログ、一時
ファイルも不要な場合は %LOCALAPPDATA%\video-enhance-lite\ を削除できます。
生成済みの動画は出力先に残るため、必要に応じて別途管理してください。
- 正式サポートは Windows 11 x64 のみです
- 外部エンジンのバージョン、GPU、Vulkan ドライバー、モデルは利用者環境に依存します
- GUI の実表示テストは表示環境が必要です。headless 環境では marker により分離します
e2eテストは実 FFmpeg とVIDEO_ENHANCE_E2E_RIFE_DIRがある環境でのみ実行します- 出力 container は MP4 固定です。非対応ストリームを変換・削除する option は未実装です
- VFR normalizationはsourceの局所PTSを保存する方式ではなく、nominal fpsへの明示CFR化です
python -m pip install -e ".[dev,enhance]"
python -m pytest tests/enhance -q -m "not gui and not requires_display and not e2e"
python -m pytest tests/release -q
python -m ruff check src tests
python -m build
外部バイナリ、モデル、入力・出力メディア、.local の実設定を source tree に追加
しないでください。詳細は CONTRIBUTING.md と THIRD-PARTY-NOTICES.md を参照します。
第一者コードは MIT License の下で提供します。Copyright (c) 2026 Ryoichi-R and contributors. 第三者コンポーネントにはそれぞれのライセンスが 適用されます。依存関係の境界、ライセンス、公式URLは THIRD-PARTY-NOTICES.md を参照してください。