Properties
播放器 Property 的設計規則與行為。型別、預設值與範圍以程式碼為準：FlowPlayerAPI 的 PlayerVocabulary.swift。Command／Property 系統見 player-api.md。
設計
- 名稱：
類別.名稱（借鏡 mpv），Swift 以PropertyKey的靜態常數存取（如.audioVolume），或以名稱與PropertyValue存取。 - 目錄：只有登記的 Property 存在；型別、預設值、唯讀與正規化都由登記的
PropertyDescriptor決定，自建同名的PropertyKey改變不了（見目錄）。 - 可寫與唯讀：可寫 Property 表達使用者意圖，引擎觀察後套用；唯讀 Property 只由引擎回報狀態。
- 寫入：先正規化（如超出範圍取最近的值）再存入；未登記、唯讀或無效值拋
PropertyError。依名稱寫入時，數字可寫入整數 Property（須為整數）與時間 Property（秒）。未開啟媒體時照常存入，開檔時套用。 - 加減與循環：
add對數值 Property 加減，cycle切換 Bool 或依PropertyDescriptor.steps移到下一階（見 Command）；playback.rate的步階即控制列的速度選單。 - 觀察：值改變時才通知；SwiftUI 讀
value(of:)會自動更新。 - 保存：不保存。開啟新檔案時保留，結束 Flow 後回到預設值。
try player.set(.audioVolume, to: 50)
let token = player.observe(.playbackPosition) { position in … }由控制列、快捷鍵調整見 settings.md；MCP 可讀取全部 Property、設定可寫的 Property，見 mcp.md。
清單
播放
| Property | 寫入 | 行為 |
|---|---|---|
playback.state | 唯讀 | idle（未開啟媒體）、loading、ready（已載入、尚未播放）、playing、paused、seeking、ended（播完，保留最後一幀）或 error；轉移見狀態機 |
playback.path | 唯讀 | 開啟中的檔案路徑（非檔案時為 URL，同 mpv path）；開始載入時設定，stop 與失敗後為 nil。不為 nil 即已開啟媒體 |
playback.error | 唯讀 | 失敗原因（PlayerError），只在 playback.state 為 error 時不為 nil |
playback.position | 唯讀 | 播放中每 0.25 秒更新；暫停、seek、播完時立即更新；開檔、stop、開檔失敗後歸零 |
playback.duration | 唯讀 | 未開啟媒體或長度未知時為 nil |
playback.paused | 可寫 | 使用者的暫停意圖，而非播放狀態。load 開始載入時寫入其 paused 參數（預設 false，新檔案直接播放）。播完時變為 true 並保留最後一幀（mpv keep-open），再設為 false 從頭播放。play、pause Command 即寫入此值 |
playback.rate | 可寫 | 變速時音調不變 |
音訊
| Property | 寫入 | 行為 |
|---|---|---|
audio.volume | 可寫 | 音量（%） |
audio.mute | 可寫 | 不改變 audio.volume |
影像
| Property | 寫入 | 行為 |
|---|---|---|
video.rotate | 可寫 | 疊加在影片本身旋轉之上的順時針角度；變更時重新編譯 Display Graph 並更新 video.display-size，App 的視窗跟著調整比例 |
video.display-size | 唯讀 | 套用像素長寬比與旋轉（含 video.rotate）後的影片尺寸（像素），由影片軌的幾何算出，與視窗無關；開檔時（fileLoaded 之前）設定，未開啟媒體或沒有影像時為 nil。App 依它調整視窗大小並鎖定比例 |
視窗
| Property | 寫入 | 行為 |
|---|---|---|
window.fullscreen | 可寫 | App 套用到視窗，並回寫實際狀態（含系統綠色按鈕） |