麟曜文件

HUAN 讙 · 使用教學

在 Raspberry Pi 上安裝

檢視 Markdown在 ChatGPT 開啟在 Claude 開啟

Raspberry Pi 是 HUAN 的主要目標裝置，但產品沒有綁死在它上面。同一份程式碼也跑在 Ubuntu、Windows 與 macOS 上。

建議規格

項目需求
機型Raspberry Pi 4 以上
作業系統Raspberry Pi OS 64-bit（Bookworm 以上）
記憶體最低 2GB，建議 4GB
儲存32GB 以上的 A2 等級 microSD，或 USB SSD
網路有線網路優先

安裝

從 Releases 下載 linux-arm64 的版本。

AppImage：

chmod +x HUAN-Device-*-linux-arm64.AppImage
./HUAN-Device-*-linux-arm64.AppImage

Debian 套件：

sudo apt install ./HUAN-Device-*-linux-arm64.deb
huan-device

開機自動啟動

Raspberry Pi OS 使用 systemd，但 HUAN 不假設系統上一定有 systemd——它只是最常見的情況。

# ~/.config/systemd/user/huan-device.service
[Unit]
Description=HUAN Device Player
After=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/huan-device
Restart=always
RestartSec=10

[Install]
WantedBy=graphical-session.target
systemctl --user enable --now huan-device
loginctl enable-linger "$USER"   # 讓服務在沒有登入時也能執行

螢幕設定

關閉螢幕保護與休眠

sudo apt install xscreensaver
xset s off
xset -dpms
xset s noblank

或在 ~/.config/wayfire.ini 加上：

[idle]
dpms_timeout = -1
screensaver_timeout = -1

直式螢幕

# Wayland（Raspberry Pi OS Bookworm 預設）
wlr-randr --output HDMI-A-1 --transform 90

版面的畫布尺寸要跟著改成 1080×1920。裝置回報的顯示器資訊會反映實際的方向，建立版面時可以直接選「使用裝置解析度」。

影片播放

Worker 產生的播放檔已經針對 Raspberry Pi 最佳化：

  • H.264（不是 H.265）
  • yuv420p 像素格式
  • 最高 1920×1080
  • 最高 30fps

yuv420p 是刻意指定的：某些來源使用 yuv444p 或 10-bit 格式，Pi 的硬體解碼器不支援，會退回軟體解碼而卡頓。

增加 GPU 記憶體

/boot/firmware/config.txt：

gpu_mem=256

溫度

Raspberry Pi 上讀得到 CPU 溫度，會在 heartbeat 中回報，後台可以看到。

Windows 與 macOS 上讀不到，回報 null，後台顯示「—」。不會為了統一型別而編一個數字。

裝置超過 80°C 會開始降頻，畫面可能變卡。裝在密閉機殼裡的 Pi 建議加散熱片或風扇。

沒有的假設

HUAN 不會假設系統上一定存在：

  • apt
  • vcgencmd
  • systemd

這些平台差異都封裝在 PlatformAdapter 介面裡。讀不到的資訊回報 null，不會讓播放器崩潰。

疑難排解

畫面全黑但程式在跑：檢查 HDMI 是不是被偵測成未連接。Pi 在開機時沒接螢幕會停用輸出。

影片卡頓：確認素材真的是 H.264 / yuv420p（後台的素材詳情看得到），並增加 GPU 記憶體。

同步很慢：Wi-Fi 在多數場地都不穩定，有線網路差很多。

磁碟空間不足：後台會顯示裝置回報的儲存錯誤。清掉不需要的排程與版面可以讓裝置回收對應的素材。