epochaudio/coverart repository overview

docker pull epochaudio/coverart:3.1.6

## 快速安装 / Quick Start

准备持久化目录和配置文件：

mkdir -p /cache/Roonart/images /cache/Roonart/config
cd /cache/Roonart
test -f config.json || printf '{}\n' > config.json
test -f config/local.json || printf '{\n  "server": {\n    "port": "3666"\n  }\n}\n' > config/local.json

启动容器：

docker run -d \
  --name roon-coverart \
  --network host \
  --restart unless-stopped \
  -e ROON_PERSIST_PATH=/app/config.json \
  -v "$(pwd)/config.json:/app/config.json" \
  -v "$(pwd)/config/local.json:/app/config/local.json:ro" \
  -v "$(pwd)/images:/app/images" \
  epochaudio/coverart:3.1.6

访问：

http://<docker-host-ip>:3666

首次启动后，在 Roon 中进入 Settings -> Extensions，启用 CoverArt_Square_Docker。授权状态会写入宿主机的 config.json，升级或重建容器时请保留该文件。

## Docker Compose

推荐从 GitHub 仓库使用 docker-compose.yml：

docker pull epochaudio/coverart:3.1.6
COVERART_IMAGE=epochaudio/coverart:3.1.6 docker compose up -d

Compose 默认挂载：

- ./config.json -> /app/config.json：保存 Roon 授权与扩展状态
- ./config/local.json -> /app/config/local.json：覆盖应用配置
- ./images -> /app/images：保存封面图

## 宿主机键盘控制 / Host Keyboard Control

3.1.6 增加宿主机键盘控制。容器可以读取 Docker 宿主机的 /dev/input 键盘事件并直接控制 Roon。

键盘监听默认启用；如果没有键盘或设备打不开，只会输出 warning，不影响网页和 Roon 扩展启动。需要关闭时设置：

KEYBOARD_ENABLED=false

默认按键映射：

- KEY_RIGHT / KEY_NEXTSONG: 下一曲 / Next
- KEY_LEFT / KEY_PREVIOUSSONG: 上一曲 / Previous
- KEY_SPACE / KEY_PLAYPAUSE: 播放/暂停 / Play or pause
- KEY_UP / KEY_PLAY: 播放 / Play
- KEY_DOWN / KEY_STOP / KEY_STOPCD: 停止 / Stop
- KEY_PAUSE: 暂停 / Pause

### Docker Run with Keyboard

常规 Linux 发行版通常会把 /dev/input/event* 设为 root:input。先查询 input 组 GID：

getent group input

然后启动：

docker run -d \
  --name roon-coverart \
  --network host \
  --restart unless-stopped \
  --group-add "$(getent group input | cut -d: -f3)" \
  --device-cgroup-rule='c 13:* rwm' \
  -e ROON_PERSIST_PATH=/app/config.json \
  -e KEYBOARD_ENABLED=true \
  -e KEYBOARD_DEBOUNCE_MS=180 \
  -v /dev/input:/dev/input:ro \
  -v "$(pwd)/config.json:/app/config.json" \
  -v "$(pwd)/config/local.json:/app/config/local.json:ro" \
  -v "$(pwd)/images:/app/images" \
  epochaudio/coverart:3.1.6

某些精简系统会把 /dev/input/event* 设为 root:root 且权限为 0600，没有可用的 input 组。这时可让容器以 root 用户读取只读输入设备：

docker run -d \
  --name roon-coverart \
  --network host \
  --restart unless-stopped \
  --user root \
  --device-cgroup-rule='c 13:* rwm' \
  -e ROON_PERSIST_PATH=/app/config.json \
  -e KEYBOARD_ENABLED=true \
  -e KEYBOARD_DEBOUNCE_MS=180 \
  -v /dev/input:/dev/input:ro \
  -v "$(pwd)/config.json:/app/config.json" \
  -v "$(pwd)/config/local.json:/app/config/local.json:ro" \
  -v "$(pwd)/images:/app/images" \
  epochaudio/coverart:3.1.6

## Compose Keyboard Override

GitHub 仓库提供 docker-compose.keyboard.yml。在 .env 中设置：

INPUT_GID=106
KEYBOARD_ENABLED=true
KEYBOARD_CONTAINER_USER=node
KEYBOARD_DEVICE=
KEYBOARD_DEVICES=
KEYBOARD_DEBOUNCE_MS=180

启用：

docker compose -f docker-compose.yml -f docker-compose.keyboard.yml up -d

如果宿主机输入设备是 root:root 0600：

INPUT_GID=0
KEYBOARD_CONTAINER_USER=root

建议优先使用稳定设备路径：

KEYBOARD_DEVICE=/dev/input/by-id/your-keyboard-event-kbd
KEYBOARD_DEVICES=/dev/input/by-id/kbd1-event-kbd,/dev/input/by-id/kbd2-event-kbd

不要优先使用 /dev/input/event3 这类编号，因为重启后编号可能变化。

## 升级 / Upgrade

保留 config.json、config/local.json 和 images 后更新镜像：

docker pull epochaudio/coverart:3.1.6
COVERART_IMAGE=epochaudio/coverart:3.1.6 docker compose up -d

如果只是更新镜像且容器创建参数没有变化，重新拉取镜像后重建/重启即可。如果新增宿主机键盘控制所需的 /dev/input 挂载、--device-cgroup-rule 或用户权限参数，需要重新创
建容器。

## Links

- GitHub: https://github.com/epochaudio/RoonCoverArt_Square_Frame_Docker
- Release v3.1.6: https://github.com/epochaudio/RoonCoverArt_Square_Frame_Docker/releases/tag/v3.1.6


Short description 可以填：

```text
Roon Cover Art square display for Docker with host keyboard control