前提として、この記事もAI(Muse)の支援を受けて記述しています。仕様・判断・最終検収は筆者自身が行っています。
この記事で分かること
- フルスクリーンでツールバーが居座る原因は、NSToolbarを隠す制御そのものが無かったこと
- 復帰トリガーを画面の一番上5ptだけに絞り、判定を純粋な状態機械に切り出してテストで全パターンを検証した設計(プレイヤー系スイート260/260)
- 「直った」ことを目視ではなく、バー表示時と非表示時の映像ピクセル差分0で確認した検証
はじめに
個人で商用ソフト「Megrab Studio」(動画ダウンローダ。Windows / macOS / Android)を開発しています。
Mac版のプレイヤーを実機で触っていて、自分で見つけた不具合の話です。フルスクリーンで動画を再生しても、アプリの上部バー(ツールバー)が常時表示されたままで、その分だけ映像が下に押し下げられていました。
動画プレイヤーでフルスクリーンにする理由は、映像を大きく、余計なものなしで見るためです。バーが居座るのは、その目的と真逆の状態でした。
原因:NSToolbarには「隠す制御」が無かった
上部バーの実体は、SwiftUIの .toolbar で定義された AppKit の NSToolbar(unifiedスタイル)でした。フルスクリーンになっても isVisible は true のままで、プレイヤー再生中に隠す制御がどこにも無かった、というのが原因です。
なお、別ウィンドウに切り離したプレイヤーには NSToolbar 自体が存在しません(デバッガで toolbar == nil を確認)。なので対象は「メインウィンドウでフルスクリーン再生している場合」だけ、と最初に絞りました。直す範囲を絞るのは、壊す範囲を絞ることでもあります。
設計:状態機械にして、時刻と座標を注入できる形に
実装は2つに分けました。
-
FullScreenTopBarPolicy.swift:いつ出す/いつ隠すかだけを決める純粋な状態機械。時刻、バー高、上端帯、猶予時間を外から注入できる -
FullScreenTopBarController.swift:NSEventのローカル監視でマウス移動を受け取り、ポリシーに問い合わせてtoolbar.isVisibleを切り替える
ポリシーを純粋な状態機械にしたのは、テストのためです。「何秒経ったら隠れるか」「どの位置なら出すか」は、実機でマウスを動かして目視するより、単体テストで全パターンを回す方が確実に検証できます。
採用した値は、実測ベースでこの3つです。
| 項目 | 値 | 備考 |
|---|---|---|
| 復帰トリガー(上端帯) | 5pt | 画面の一番上 5pt にカーソルが触れたときだけ出す |
| バー領域 | 52pt | ツールバーの実測の高さ |
| 非表示までの猶予 | 1.0秒 | カーソルが離れてから隠れるまでの間 |
ポイントは復帰トリガーを「バー領域全体(52pt)」ではなく「上端帯(5pt)」だけにしたことです。バーを隠している間、映像の上の方にカーソルを持っていくことは普通にあります。そのたびにバーが出たら、隠す意味がありません。
例外として、次の状態ではバーを保持します。
- 検索フィールドを編集中
- シートやモーダルが表示中
- マウスボタンを押している最中
表示切替で映像をリサイズしない
バーの表示・非表示は toolbar.isVisible の切り替えだけで行い、映像側には .ignoresSafeArea() を付けて、バーの状態に映像領域が引きずられないようにしました。
ここは後述の検証で効いてきます。「バーを隠したら映像がその分大きくなった」では、直したことにはなりません。求めたのは「映像の位置と大きさはそのままに、バーだけが出たり消えたりする」挙動です。
なお、この自動非表示はプレイヤーのHUD(操作パネル)とは独立に動きます。Up Next の「自動」表示は従来どおりHUDの表示状態にだけ連動させ、ポリシーは混ぜませんでした。バー表示中は重ならないようHUD側の上部余白だけ調整しています(バー非表示時は余白が残る、というトレードオフは明示した上で受け入れました)。
テストが効いた実例:初回は失敗した
正直に書くと、初回のテストでは不具合が見つかりました。「非表示中にバー領域(5〜52pt)へカーソルを移動すると、バーが出てしまう」というものです。設計意図(出すのは上端帯5ptだけ)と実装が食い違っていました。
これをエージェント自身がテストで検出し、状態機械を直して再実行、という流れで解消しました。最終結果は次の通りです。
- プレイヤー系スイート:260/260(既存215+新規45)
- 全40スイート:PASS
「AIに実装させると、テストは明記しないと省略される」というのが自分の持論ですが、今回は逆に、テストを書かせたからこそ設計意図とのズレが機械的に見つかった、という事例になりました。
検証:スクリーンショットとピクセル差分
実機での確認は、スクリーンショット11枚でケースを並べて行いました。
- 既定では非表示になっている
- y=30pt(バー領域内)では出ない
- y=1pt(上端帯)では出る
- 離脱後は再び隠れ、その間もHUDは表示され続ける
- クリックでは出ない
- Escと終了ボタンの両方でフルスクリーンを抜けられる
- 通常表示(フルスクリーンでない状態)は従来と変わらない
そして一番大事な確認が、映像中央領域のピクセル差分が、バー表示時と非表示時で 0 だったことです。「映像がリサイズされていない」を目視ではなく数値で言える状態にしました。
未実施の確認も正直に書いておきます。システムのメニューバー自動表示との組み合わせと、マルチディスプレイでの見え方は未確認です。ディスプレイが1台の環境なので、ここは単体テスト担保の範囲を超えていません。
まとめ
- フルスクリーンでバーが居座る原因は、NSToolbarを隠す制御そのものが無かったこと
- 出す条件は「画面の一番上 5pt」だけに絞り、バー領域では出さない。これが体感を決める
- 判定は純粋な状態機械に切り出すと、出す/隠すの全パターンをテストで回せる
- 「直った」の判定は目視ではなく、ピクセル差分 0 という数値で行う
小さい修正ですが、プレイヤーの使用感はこういう「1フレームも映像を邪魔しない」部分の積み重ねで決まるのだと思います。
レイノワークスとして、Windows / macOS / Android 向けの個人開発をしています。
この記事はZennにも掲載しています:https://zenn.dev/ray_9618/articles/35b733c78c515a