Media Player Technical Document

プログラムの動作

media_player.py は、PySide6ライブラリを使用して構築されたデスクトップ向けのシンプルなメディアプレイヤーです。動画ファイルを再生し、一時停止、停止、再生位置のシーク、再生速度の調整といった基本的な制御機能を提供します。また、起動時のファイル指定、ドラッグ＆ドロップによるファイル読み込み、およびウィンドウの位置とサイズの自動保存・復元機能も備えています。

主な機能:

メディア再生: MP4, MOV, MKV, AVI形式の動画ファイルを再生できます。
再生制御: 再生、一時停止、停止、再生開始位置への巻き戻し。
シーク機能: スライダーを操作して再生位置を自由に移動できます。
再生速度調整: スライダーで0.5倍速から2.0倍速まで再生速度を変更できます。
ファイルオープンダイアログ: GUIからファイルを選択して開くことができます。
ドラッグ＆ドロップ: プレイヤーウィンドウに動画ファイルを直接ドラッグ＆ドロップして再生を開始できます。
コマンドライン引数: 起動時に再生するファイルを指定したり、自動再生を設定したり、ファイル選択ダイアログの表示を制御したりできます。
ウィンドウ状態の保存: ウィンドウのサイズと位置を player_config.ini ファイルに自動的に保存し、次回起動時に復元します。

解決する課題:

複雑な機能を持たない、軽量で直感的に操作できる動画プレイヤーを求めるユーザーに対し、基本的な再生機能と使いやすさを提供します。特に、コマンドラインからのファイル指定やドラッグ＆ドロップによる迅速なファイルオープンは、日常的なメディア視聴の利便性を向上させます。

原理

本プログラムは、主に以下の技術とアルゴリズムに基づいて動作します。

GUIフレームワーク (PySide6):
- QtのPythonバインディングであるPySide6を利用して、アプリケーションのユーザーインターフェースを構築しています。QMainWindow をメインウィンドウとし、QVideoWidget で映像を表示、QPushButton や QSlider で再生制御を行っています。
- 各種ウィジェットの配置には QVBoxLayout (垂直レイアウト) と QHBoxLayout (水平レイアウト) を使用しています。
メディア再生エンジン (QMediaPlayer):
- PySide6の QtMultimedia モジュールに含まれる QMediaPlayer クラスがメディアファイルのロード、再生、一時停止、停止、シーク、再生速度調整など、全てのメディア処理を担います。
- 音声出力には QAudioOutput を、映像表示には QVideoWidget を QMediaPlayer に設定することで、統合されたメディア再生が実現されます。
- シグナルとスロット: QMediaPlayer の durationChanged シグナル (メディアの総再生時間が変更されたとき) を duration_changed スロットに接続してシークスライダーの最大値を設定し、positionChanged シグナル (現在の再生位置が変更されたとき) を position_changed スロットに接続してスライダーの現在値を更新しています。
ドラッグ＆ドロップ (DnD):
- QMainWindow クラスの setAcceptDrops(True) を呼び出すことで、ウィンドウ全体でドラッグ＆ドロップイベントを受け入れるように設定しています。
- dragEnterEvent(event: QDragEnterEvent) をオーバーライドし、ドロップされる可能性のあるデータ（この場合はURL）がサポートされているメディアファイル形式であるかを簡易的にチェックし、イベントを受け入れる (event.acceptProposedAction()) か無視する (event.ignore()) かを決定します。
- dropEvent(event: QDropEvent) をオーバーライドし、実際にファイルがドロップされたときにそのURLからローカルファイルパスを取得し、load_media() メソッドを呼び出してファイルをロード・再生します。
設定ファイルの読み書き (configparser):
- Python標準ライブラリの configparser モジュールを使用して、ウィンドウのサイズと位置などの設定を player_config.ini というINIファイル形式で永続化しています。
- load_window_geometry() メソッドで起動時にINIファイルから設定を読み込み、save_window_geometry() メソッドでウィンドウが閉じられる際に現在の設定をINIファイルに書き込みます。
コマンドライン引数解析 (argparse):
- Python標準ライブラリの argparse モジュールを使用して、コマンドラインから渡される引数 (infile, --autoplay, --ask_open) を解析します。
- これにより、起動時に特定のファイルをロードしたり、そのファイルを自動再生したり、ファイル指定がない場合にファイル選択ダイアログを表示したりといった柔軟な挙動が可能になります。
モジュール依存性チェック:
- check_imports 関数は、プログラムが実行を開始する前に必要な非標準ライブラリ（PySide6 など）がシステムにインストールされているかを確認します。これにより、必要な依存関係が満たされていない場合に早期にエラーを通知し、ユーザーにインストール方法を提示することができます。

必要な非標準ライブラリとインストール方法

media_player.py を実行するには、以下の非標準ライブラリが必要です。

PySide6: Qt for Pythonの公式バインディングで、GUIアプリケーションを構築するために使用されます。
```
pip install PySide6
```
configparser: Pythonの標準ライブラリですが、check_imports 関数で明示的にチェックされるため、一応インストールコマンドを記載します（通常は別途インストールは不要です）。
```
pip install configparser
```

必要な入力ファイル

media_player.py は、以下の種類のメディアファイルを処理できます。

メディアファイル:
- 形式: MP4 (.mp4), QuickTime (.mov), Matroska (.mkv), AVI (.avi)
- 説明: 再生したい動画ファイル。プログラムはこれらのファイルタイプをサポートしており、ファイルダイアログやドラッグ＆ドロップで認識します。
- 例: my_video.mp4, movie.mkv
player_config.ini (任意):
- 形式: INIファイル形式
- 説明: ウィンドウの最後の位置とサイズを保存する設定ファイルです。このファイルはプログラムが初めて実行されるか、存在しない場合に自動的に生成されます。ユーザーが手動で作成する必要はありません。
- データ構造:
```
[Window]
geometry = x,y,width,height
```
  - x, y: ウィンドウの左上隅のX, Y座標
  - width, height: ウィンドウの幅と高さ

生成される出力ファイル

プログラムは、実行時に以下のファイルを生成または更新します。

player_config.ini:
- 保存場所: media_player.py スクリプトと同じディレクトリ。
- 内容: プレイヤーウィンドウが閉じられる際に、その時点のウィンドウの位置 (x, y) とサイズ (width, height) を保存します。この情報は次回プログラム起動時に読み込まれ、ウィンドウが以前と同じ状態に復元されます。
- 例:
```
[Window]
geometry = 100,50,800,600
```
  これは、ウィンドウが画面座標 (100, 50) に位置し、幅が800ピクセル、高さが600ピクセルであったことを示します。

コマンドラインでの使用例 (Usage)

media_player.py は、以下の形式でコマンドラインから実行できます。

python media_player.py [infile] [--autoplay] [--ask_open]

引数の説明:

infile:
- 型: 文字列 (ファイルパス)
- オプション: 任意
- 説明: プログラム起動時に自動的にロードするメディアファイルのパスを指定します。この引数が省略された場合、プレイヤーはメディアがロードされていない状態で起動します。
--autoplay:
- 型: フラグ (ブーリアン)
- オプション: 任意
- 説明: infile が指定されている場合に、ロード後にメディアの再生を自動的に開始します。このフラグがない場合、ファイルはロードされますが、再生は一時停止状態で開始します。
--ask_open:
- 型: フラグ (ブーリアン)
- オプション: 任意
- 説明: infile が指定されていない場合に、メディアファイルを選択するためのファイルダイアログを自動的に表示します。ユーザーがファイルを選択しなかった場合、プログラムは終了します。

コマンドラインでの具体的な使用例

ここでは、media_player.py をコマンドラインから実行する具体的な例とその動作について説明します。

基本的な起動 (ファイル指定なし)
```
python media_player.py
```
実行結果: メディアファイルが何もロードされていない状態でプレイヤーウィンドウが開きます。ユーザーは「Open File」ボタンをクリックするか、動画ファイルをウィンドウにドラッグ＆ドロップして再生を開始できます。
特定のファイルをロードして起動 (自動再生なし) video.mp4 という名前の動画ファイルが現在のディレクトリにあると仮定します。
```
python media_player.py video.mp4
```
実行結果: video.mp4 がロードされ、プレイヤーウィンドウのタイトルバーにファイル名が表示されます。再生は一時停止状態で開始するため、ユーザーが「▶ Play」ボタンをクリックする必要があります。
特定のファイルをロードし、自動で再生を開始 another_video.mkv という名前の動画ファイルが現在のディレクトリにあると仮定します。
```
python media_player.py another_video.mkv --autoplay
```
実行結果: another_video.mkv がロードされると同時に、自動的に再生が開始されます。
ファイルが指定されていない場合にファイル選択ダイアログを表示
```
python media_player.py --ask_open
```
実行結果: ファイル選択ダイアログが自動的に表示されます。ユーザーがファイルを選択して「開く」をクリックすると、そのファイルがロードされ、再生が開始されます。ユーザーがダイアログをキャンセルした場合、プログラムは終了します。
存在しないファイルを指定した場合 non_existent_file.mp4 というファイルが存在しないと仮定します。
```
python media_player.py non_existent_file.mp4
```
実行結果: コンソールに「Warning: Specified file not found: non_existent_file.mp4. Proceeding without initial file.」という警告が表示され、ファイルが何もロードされていない状態でプレイヤーウィンドウが開きます。これは、ファイルが見つからない場合でもアプリケーションがクラッシュせずに起動し、ユーザーに手動でファイルを選択する機会を与えるための挙動です。