SoftPlayer 使用手冊

在目標機上完成解壓並確認執行環境滿足需求。

1. 確認執行機器為 Windows 10/11 x64 系統。
2. 將 SoftPlayer 壓縮包解壓到固定目錄，例如 C:\SoftPlayer\。
3. 解壓後確認目錄中存在 SoftPlayer.exe、appsettings.json、SoftPlayerMedia\ 子目錄結構。
4. 如需播放 8K 影片，確認機器有支援硬體解碼的獨立顯示卡（GTX 1060+ 或同等）；4K 及以下整合顯示卡即可使用。

• 解壓目錄中可以看到 SoftPlayer.exe。
• SoftPlayerMedia\ 目錄已自動預建，包含 Video、StandBy、Audio、PPT 等子目錄。

• 建議把 SoftPlayer 放到固定路徑，因為媒體檔案、日誌和授權狀態都儲存在程式同級目錄。
• SSD 儲存讀取速度建議 200MB/s+，4K 影片更流暢。

確認程式正常啟動並完成首次引導。

1. 雙擊 SoftPlayer.exe 啟動程式（無需系統管理員權限）。
2. 首次啟動時，程式會用預設瀏覽器開啟快速上手.html 引導頁（僅首次，後續啟動不再彈出）。
3. 引導頁閱讀完畢後，在瀏覽器中訪問 http://localhost:8766/ 進入管理台。
4. 在管理台儀表板中確認播放器狀態顯示正常，版本號和授權狀態可見。

• 瀏覽器成功開啟管理台（http://localhost:8766/），儀表板顯示播放器狀態。
• 管理台頂部顯示目前版本號和授權狀態。

如需停用首次啟動引導，在 appsettings.json 中將 System.ShowQuickStartOnFirstRun 改為 false。

透過 UDP 成功控制播放器，確認控制鏈路暢通。

1. 把一個影片檔案（例如 test.mp4）放到 SoftPlayerMedia\Video\ 目錄。
2. 開啟 PowerShell，執行以下命令發送播放指令：
3. $udp = New-Object System.Net.Sockets.UdpClient
4. $data = [System.Text.Encoding]::UTF8.GetBytes("video:test.mp4")
5. $udp.Send($data, $data.Length, "127.0.0.1", 7600)
6. $udp.Close()
7. 觀察 SoftPlayer 視窗是否開始播放該影片。

• SoftPlayer 視窗開始播放指定影片檔案。
• 管理台日誌頁可以看到收到命令的記錄。

• 影片檔案放錯目錄（應放到 SoftPlayerMedia\Video\，而不是程式根目錄）。
• 埠號寫錯（預設 7600，注意不是管理台的 8766）。

掌握命令格式，理解成功和失敗響應的區別。

1. 命令格式：命令名:參數，例如 video:show.mp4 或 volume:80。
2. 無參命令直接發命令名，例如 play: 或 stop:（冒號可省略）。
3. 成功響應格式：OK:原始命令，例如 OK:video:show.mp4。
4. 失敗響應格式：ERR:原始命令:錯誤資訊。
5. 媒體檔案路徑只需寫檔案名稱（不含子目錄路徑），播放器會自動在對應子目錄查找：video: 命令在 SoftPlayerMedia/Video/ 下查找。

• 發送命令後能收到 OK 開頭的響應，說明命令格式正確且被執行。
• 收到 ERR 響應時，錯誤資訊會指出具體原因（檔案不存在、格式錯誤等）。

如需指定子目錄，可用斜線分隔：video:subfolder/video.mp4 會在 SoftPlayerMedia/Video/subfolder/ 下查找。

掌握影片播放相關的全部命令。

1. 播放本機影片：video:檔案名稱.mp4（在 Video 目錄查找）。
2. 播放網路影片串流：webvideo:URL（支援 HTTP/HTTPS/RTSP/RTMP/UDP 串流）。
3. 播放/恢復：play:（恢復暫停的媒體）。
4. 暫停：pause:（暫停目前媒體）。
5. 停止並切回待機：stop:（回到歡迎畫面/待機循環）。
6. 徹底停止黑屏：stoped:（關燈節電語義，純黑屏）。
7. 重新播放目前媒體：replay:。
8. 進度控制：seek:毫秒數（跳轉到指定位置）、forward:（前進10秒）、backward:（後退10秒）。
9. 播放速度：speed:1.5（支援 1.5/2.0 等倍速）。

• video: 命令執行後播放器開始播放該檔案。
• stop: 命令執行後返回待機畫面（如果設定了待機檔案）。

• 展廳長時間待機建議使用 standby: 命令切到待機檔案循環，而不是 stoped: 黑屏（黑屏可能讓觀眾認為設備故障）。
• stop 與 stoped 語義不同：stop 切回歡迎畫面，stoped 是純黑屏。

掌握音量調節和音訊播放控制命令。

1. 設定音量（0-100）：volume:80（直接設定到指定值）。
2. 音量加 10%：volup:（每次呼叫增加 10%）。
3. 音量減 10%：voldown:（每次呼叫減少 10%）。
4. 靜音切換：mute:（在靜音/非靜音之間切換）。
5. 明確開啟靜音：muteon:。
6. 明確取消靜音：muteoff:。
7. 播放音訊檔案：audio:檔案名稱.mp3（在 SoftPlayerMedia/Audio/ 查找）。
8. 停止音訊：audiostoped:。

• volume:50 命令執行後，播放器音量降到 50%。
• mute: 命令可在有聲和靜音間切換。

掌握循環清單、PPT 翻頁和網頁載入命令。

1. 循環播放清單：listloop:檔案1.mp4;檔案2.mp4;檔案3.mp4（用分號分隔多個檔案）。
2. 順序播放（播完停止）：liststop:檔案名稱。
3. 清單下一首：next:，上一首：prev:。
4. 開啟 PPT 全螢幕播放：ppt:檔案名稱.pptx（在 SoftPlayerMedia/PPT/ 查找）。
5. PPT 翻頁：ppt:next（下一頁）、ppt:prev（上一頁）、ppt:home（第一頁）、ppt:end（最後一頁）。
6. PPT 跳頁：ppt:goto-5（跳轉到第5頁）。
7. PPT 自動翻頁：ppt:auto-5-檔案名稱.pptx（每5秒自動翻頁）。
8. 載入網頁：web:URL（全螢幕顯示指定網頁）。

• listloop: 命令執行後播放器開始循環播放清單中的檔案。
• ppt:next 執行後 PPT 翻到下一頁。

• PPT 檔案需提前放入 SoftPlayerMedia/PPT/ 目錄。
• 如果 PPT 是 PDF 格式，會退化為檢視器視窗加按鍵模擬翻頁。
• 展廳常用循環播放場景建議用 listloop 而不是手動逐個發命令。

了解遮罩和系統級命令的用法。

1. 顯示遮罩：openmask:（在影片上疊加遮罩層）。
2. 隱藏遮罩：closemask:。
3. 設定播放結束行為：endbehavior:Stop（停止）/ Loop（循環）/ Standby（切待機）。
4. 取得版本號：version:（回執中包含目前版本資訊）。
5. 重啟播放器：restart:（遠端重啟播放器行程）。

• openmask: 執行後影片上出現遮罩覆蓋層。
• version: 執行後收到包含版本資訊的回執。

了解媒體檔案的正確存放位置。

1. SoftPlayerMedia/Video/ — 存放影片檔案（.mp4/.mkv/.avi 等），video: 命令在此查找。
2. SoftPlayerMedia/StandBy/ — 存放待機檔案，standby: 命令和開機預設播放使用此目錄。
3. SoftPlayerMedia/Audio/ — 存放音訊檔案（.mp3/.wav/.flac 等），audio: 命令在此查找。
4. SoftPlayerMedia/BackgroundAudio/ — 背景音訊目錄，啟用後自動循環播放。
5. SoftPlayerMedia/PPT/ — 存放 PPT/PDF 檔案，ppt: 命令在此查找。
6. SoftPlayerMedia/Mask/ — 存放遮罩圖片，openmask: 命令使用此目錄。
7. SoftPlayerMedia/Thumbnail/ — 縮圖快取目錄（自動產生，無需手動放檔案）。

• 將影片檔案放到 Video/ 目錄後，用 video:檔案名稱 命令可以正常播放。
• 目錄結構在首次啟動時自動建立，無需手動建立目錄。

透過瀏覽器管理台完成媒體檔案的日常管理。

1. 在瀏覽器中開啟 http://播放器IP:8766/ 進入管理台。
2. 點擊頂部導覽切換到「檔案」標籤。
3. 在檔案管理頁面選擇目標目錄（Video / StandBy / Audio / PPT 等）。
4. 點擊「上傳」按鈕選擇檔案，或將檔案拖曳到上傳區。
5. 支援建立資料夾、重新命名、刪除檔案/資料夾、下載檔案等操作。
6. 檔案最多支援 3 層子目錄深度，上傳時選擇目前目錄即可。

• 上傳完成後在檔案清單中可以看到新檔案。
• 透過 video:檔案名稱 命令可以成功播放剛上傳的檔案。

• 管理台使用 Basic Auth 認證，使用者名稱和密碼在 appsettings.json 中設定。
• 單一檔案上傳限制預設為 500MB，可在設定檔修改。
• 現場運維人員無需 RDP 遠端桌面即可透過管理台上傳替換內容。

了解試用期規則，合理規劃授權時間。

1. 首次執行 SoftPlayer 後自動進入 30 天試用期。
2. 試用期間全功能可用，包括高解析度播放和所有 UDP 命令。
3. 在瀏覽器管理台「儀表板」可查看剩餘試用天數。
4. 試用期結束後，需要匯入正式授權碼才能繼續使用。

• 管理台儀表板顯示目前為試用狀態及剩餘天數。
• 試用期內命令控制正常響應，無功能限制。

• 試用期建議在正式專案交付前完成測試和驗收。
• 臨近試用期結束時及時聯繫購買，避免現場授權到期影響展廳運營。

根據實際展廳解析度需求選擇合適的授權檔位。

1. 標準版授權：支援最高 4K（3840×2160）解析度輸出。
2. 專業版授權：支援最高 16K（15360×8640）解析度輸出。
3. 4K 播放硬體需求：Intel i3+ / 8GB 記憶體 / 整合顯示卡即可（無需獨立顯示卡）。
4. 8K 播放硬體需求：Intel i5 第8代+ / 16GB 記憶體 / GTX 1060+。
5. 16K 播放硬體需求：Intel i7+ / 32GB 記憶體 / RTX 3070+。
6. 如不確定所需檔位，可先試用確認實際解析度需求後再購買。

• 明確專案所用顯示設備的最大解析度，對應選擇標準版或專業版。
• 採購前確認伺服器硬體設定滿足對應解析度的最低需求。

無獨立 GPU 的電腦可以播放 4K 及以下影片（程式自動選擇軟體解碼），但播放 8K/16K 需要符合條件的獨立顯示卡。

完成授權碼的取得與匯入，將試用版升級為正式版。

1. 在瀏覽器管理台「儀表板」頁面找到「設備 ID」欄位，複製該 ID。
2. 將設備 ID 提供給供應商，說明所需授權檔位（標準版/專業版）。
3. 收到授權碼後，在管理台「設定」標籤中找到「授權管理」區域。
4. 將授權碼貼上到輸入框，點擊「匯入授權」。
5. 匯入成功後，儀表板的授權狀態從「試用」變為「標準版」或「專業版」。

• 管理台儀表板授權狀態顯示為正式版（標準版或專業版）。
• 高解析度影片播放不再受解析度限制。

• 把授權碼套用到錯誤的設備（授權碼與設備 ID 綁定，換機後需重新申請）。
• 試用期已過才開始申請授權，導致展廳停播等待授權。

恢復 UDP 命令控制鏈路。

1. 確認 SoftPlayer 正在執行（工作列或工作管理員中可見）。
2. 確認發送的埠號與 appsettings.json 中 Network.UdpPort 設定一致（預設 7600）。
3. 檢查 Windows 防火牆是否放行了 UDP 7600 埠入站規則。
4. 如果啟用了 IP 白名單（IpWhitelistEnabled: true），確認發送方 IP 在 AllowedIps 清單中。
5. 在管理台「日誌」標籤查看是否有命令接收記錄，確認命令是否到達播放器。

• 管理台日誌中出現命令接收記錄，說明 UDP 通道正常。
• 發送 volume:50 命令後播放器音量變化。

• 區域網路測試時先用 127.0.0.1（本機）驗證，排除網路問題後再換實際 IP。
• 如需從 SoftControl 發命令，確認 SoftControl 的 UDP 指令協定和埠號與 SoftPlayer 設定一致。

排查並解決媒體檔案播放失敗的問題。

1. 確認影片檔案確實存放在 SoftPlayerMedia\Video\ 目錄（不是程式根目錄）。
2. 檔案名稱區分大小寫，確認命令中的檔案名稱與實際檔案名稱完全一致（包含副檔名）。
3. 如果檔案在子目錄，命令應包含相對路徑：video:subfolder/video.mp4。
4. 在管理台「檔案」標籤瀏覽目錄，確認檔案確實存在。
5. 如果檔案格式特殊，查看管理台日誌中的錯誤資訊確認 VLC 是否支援。
6. 嘗試用 VLC 播放器在本機直接開啟同一檔案，排除檔案本身損壞的問題。

• 管理台檔案清單中能看到目標檔案。
• 命令中的檔案名稱與檔案清單中顯示的完全一致。

• 命令中寫的檔案名稱包含中文空格或全形字元，導致找不到檔案。
• 副檔名大小寫不符（如命令寫 .MP4 但檔案實際是 .mp4）。

解決高解析度影片播放效能問題。

1. 首先確認目前授權檔位：標準版僅支援 4K，專業版支援 16K。
2. 檢查顯示卡是否支援硬體解碼（GTX 1060+ 或同等，8K 需要）。
3. 在工作管理員「效能」標籤查看 GPU 解碼佔用率，如果 GPU 佔用率接近 100% 說明效能瓶頸在顯示卡。
4. 檢查硬碟讀取速度是否滿足需求：4K 需 25-50 Mbps，8K 需 80-100 Mbps，16K 需 200+ Mbps。
5. 建議將高解析度影片檔案存放在 SSD 上，避免 HDD 導致的讀取瓶頸。
6. 如需調整解碼參數，查閱程式目錄中的內建文件（docs\使用者手冊.html）取得 VLC 參數說明。

• 授權檔位與需要播放的解析度符合。
• 硬體設定滿足對應解析度的最低需求。

恢復瀏覽器管理台的訪問。

1. 確認 SoftPlayer 正在執行。
2. 本機訪問用 http://localhost:8766/ 先排除網路問題。
3. 檢查 appsettings.json 中 HttpMonitor.Enabled 是否為 true 且埠號為 8766。
4. 檢查 Windows 防火牆是否放行 TCP 8766 埠。
5. 如果埠號被其他程式占用，在 appsettings.json 中修改 HttpMonitor.Port 為其他埠號後重啟。

• 瀏覽器可以訪問 http://localhost:8766/ 並顯示管理台介面。
• 管理台「儀表板」顯示播放器執行狀態。