結論: 本スクリプトはフォルダ配下の動画を再帰的にH.265(HEVC)＋AACへ一括変換し、Apple互換性向上のため hvc1 タグ付与、音声44.1 kHz固定、拡張子自動変換、パススルー、ドライラン、CSVログ、並列処理に対応している。  
本マニュアルでは前提条件、使い方、各オプション、注意点、長時間実行の方法を整理する。

### 概要
- 目的: フォルダ内の動画を再帰的に走査し、映像は libx265、音声は環境に応じて HE-AAC v2 を優先して再エンコードし、出力構造は入力の相対階層を保持する。  
- 互換性: Appleデバイス再生のため、映像エンコード時はコンテナ内タグに hvc1 を付与する（映像パススルー時は付与しない）。  

### 前提条件
- Python 3 がインストール済みであること。  
- FFmpeg がインストール済みで、実行パスが通っていること（ffmpeg -version が動作する状態）。  

### 配置
- スクリプトファイルを任意の場所に保存し、例として encode_h265.py という名前で運用する。  
- 必要に応じて実行権限を付与するか、python3 encode_h265.py 形式で呼び出す。  

### クイックスタート
- 最小実行例（既存出力はスキップ、並列1）  
  python3 encode_h265.py --input /path/to/source --output /path/to/output  
- 進行確認のみ（ドライラン）  
  python3 encode_h265.py --input /path/to/source --output /path/to/output --dry-run  

### 入出力の挙動
- 入力フォルダ配下を再帰走査し、対象拡張子のみ処理する（.mp4 .mov .mkv .avi .flv .wmv .ts）。  
- 出力先は入力相対パス構造を維持して生成される。  

### 拡張子の扱い
- 入力が .avi/.flv/.wmv の場合、出力拡張子は自動的に .mp4 へ変更される。  
- 変更後の出力ファイル名が既に存在する場合は衝突と見なし、--overwrite の有無に関係なくスキップする。  

### エンコード仕様
- 映像: libx265、CRFとプリセットで品質/速度を調整し、エンコード時は -tag:v hvc1 を付ける。  
- 音声: 環境により HE-AAC v2 を優先し、見つからない場合はネイティブ aac にフォールバックする。  
- サンプリング周波数: 常に 44.1 kHz（-ar 44100）に変換し、チャンネルはステレオ（-ac 2）。  

### HE-AAC v2 自動検出
- aac_at（macOS）または libfdk_aac が見つかれば HE-AAC v2 を選択する。  
- aac_at の HE-AAC v2 は -profile:a 28（数値指定）で動作し、libfdk_aac は aac_he_v2 を用いる。  

### オプション一覧
- --input: 入力フォルダ（必須）。  
- --output: 出力フォルダ（必須、存在しなければ自動作成）。  
- --preset: x265プリセット（既定: medium）。  
- --crf: x265 CRF 値、低いほど高画質・大容量（既定: 28）。  
- --audio-bitrate: 音声ビットレート（既定: 32k）。  
- --log-csv: CSVログの出力パス（既定: compression_log.csv）。  
- --overwrite: 既存の出力があっても上書き（拡張子変更による衝突時は無効で常にスキップ）。  
- --workers: 並列ワーカー数（既定: 1）。  
- --dry-run: 実行せずにコマンドを表示（表示は単純連結のため、スペースを含むパスは手動で適切に引用が必要）。  
- --copy-video: 映像をパススルー（-c:v copy、x265設定と hvc1 タグは付与しない）。  
- --copy-audio: 音声をパススルー（-c:a copy、ビットレート/サンプリング/プロファイル設定は無効）。  

### 実行例
- 画質重視（CRF 24、slow、2並列）  
  python3 encode_h265.py --input ~/Videos/src --output ~/Videos/out --crf 24 --preset slow --workers 2  
- 映像パススルー、音声のみ再エンコード（32 kbps/44.1 kHz）  
  python3 encode_h265.py --input ./src --output ./out --copy-video  
- 音声パススルー、映像のみ再エンコード（hvc1タグ付与）  
  python3 encode_h265.py --input ./src --output ./out --copy-audio  
- 両方パススルー（リマックスのみ、コンテナ非対応コーデックは失敗する可能性あり）  
  python3 encode_h265.py --input ./src --output ./out --copy-video --copy-audio  

### CSVログ
- 既定は compression_log.csv に追記し、列は input, output, original_bytes, compressed_bytes, ratio, status, message。  
- ratio は圧縮率（出力 ÷ 元）で、1.000 未満はサイズ削減の目安となる。  

### 上書きとスキップ
- 既定では既存出力があればスキップし、--overwrite 指定時のみ上書きする。  
- 入力が .avi/.flv/.wmv で .mp4 に変更して衝突した場合は、--overwrite に関わらず skipped_collision としてスキップする。  

### パススルー時の注意
- ストリームコピーはコーデックとコンテナの互換性に依存するため、.mp4 非対応のコーデックをコピーすると失敗する。  
- 映像コピーと同時に hvc1 タグを強制しない仕様としており、タグ矛盾による再生不具合を避ける設計になっている。  

### ドライランの注意
- ドライランの出力は引数を単純に空白で連結して表示するため、スペースや特殊文字を含むパスは貼り付け実行時に適切な引用が必要になる。  
- 実際の処理は引数リストで安全に実行されるため、スペースを含むパスでもエンコード処理自体は問題なく動作する。  

### Apple互換性
- 映像を再エンコードする場合は -tag:v hvc1 を付与し、iOS/macOS のプレーヤーでの再生互換性を高める。  
- 映像コピー時はタグを付与しないため、コピー元が HEVC の場合にタグ整合が必要なら再エンコード運用を検討する。  

### パフォーマンスの目安
- --workers はマシンの物理コア数とディスクI/Oに応じて 1〜2 から試すと安定しやすい。  
- 同一物理ディスクで入出力が競合する場合は並列度を上げすぎると逆に遅くなる。  

### 長時間実行（ログアウト後も継続）
- 簡易: nohup を用いたバックグラウンド実行（ログは任意のファイルにリダイレクト）  
  nohup python3 encode_h265.py --input /path/to/src --output /path/to/out --workers 2 > encode.log 2>&1 &  
- Linux 常駐: systemd のユーザーサービス化＋linger（~/.config/systemd/user にサービスを作成し、systemctl --user enable --now、loginctl enable-linger を設定）。  
- macOS 常駐: launchd の LaunchDaemon を作成し、ProgramArguments に python3 とスクリプト・引数を設定、RunAtLoad/KeepAlive を有効化してロードする。  

### トラブルシューティング
- Appleで再生できない: hvc1 タグ付与は映像再エンコード時のみ行われるため、映像コピー時に互換性が必要なら再エンコードを選択する。  
- aac_at でエラー: HE-AAC v2 は -profile:a 28 を内部で使用、名称指定は不要（スクリプト側で対応済み）。  
- サンプリング周波数エラー: 44.1 kHz へ強制変換するため、入力に依存したサンプルレート不整合を回避できる。  
- ドライランを貼り付け実行して失敗: 表示は単純連結のため、スペースを含むパスは手動で引用して実行する。  
- .avi/.flv/.wmv 入力の衝突: .mp4 名の衝突はスキップされるため、出力先構成やファイル名の調整を行う。  

### ベストプラクティス
- まずドライランでコマンド内容を確認し、小規模なサブフォルダで試験実行してから本番実行する。  
- 長時間処理ではスリープや節電機能を一時的に無効化し、十分な空き容量を確保する。  

### ライセンス/注意
- libfdk_aac など外部エンコーダは配布・ライセンス条件に注意が必要な場合があるため、環境の方針に合わせて利用可否を判断する。  
- ネットワークストレージ上での処理は回線状況に影響を受けるため、必要に応じてローカルへ一時退避してから処理する。

[1](https://realpython.com/python-script-structure/)
[2](https://www.freecodecamp.org/news/python-code-examples-sample-script-coding-tutorial-for-beginners/)
[3](https://docs.python.org/3/tutorial/index.html)
[4](https://desktop.arcgis.com/en/arcmap/latest/extensions/production-mapping/setting-template-instructions-for-python-scripts.htm)
[5](https://www.assertnotmagic.com/2018/06/16/python-toolbox-make-script/)
[6](https://docs.omniverse.nvidia.com/extensions/latest/ext_python-scripting-component/user_manual.html)
[7](https://www.python.digibeatrix.com/en/faq-tips/python-scripting-writing-and-execution-guide/)
[8](https://visit-sphinx-github-user-manual.readthedocs.io/en/3.4rc/python_scripting/intro.html)
[9](https://stackoverflow.com/questions/9037828/writing-a-help-for-python-script)