Fugleramme

Fugleramme 是一款专为 Raspberry Pi 设计的开源项目，将 BirdNET-Go 的实时鸟类音频检测与公共领域 19 世纪自然历史插图结合，在 Inky Impression 13.3″ 电子墨水屏上动态呈现花园中实际出现的鸟类。所有 AI 推理完全在本地完成，不依赖云服务；艺术素材全部源自真实图版手工剪裁（非 AI 生成），覆盖 400+ 物种、800+ 插图，尤以北欧、不列颠群岛及中欧物种最为完整。

该项目核心设计理念是变化触发重绘：仅当检测到新鸟种或物种组合变化时才刷新屏幕，大幅延长电子墨水面板寿命并降低功耗。同时提供 Web Kiosk 模式，可通过 HDMI 显示器或局域网设备访问相同视图，并内置管理页面配置显示内容与自动更新策略。若已部署 BirdNET-Go，可直接指向其 API，无需重复搭建检测后端。

系统架构：解耦检测与渲染

Fugleramme 采用模块化设计，将鸟类识别与视觉呈现彻底分离：

• 检测层：BirdNET-Go 持续监听麦克风，运行分类器输出物种标签与置信度。可部署于同一 Pi 或网络内任意设备。
• 渲染层：Fugleramme 轮询 BirdNET-Go API，将物种映射至预策展插图库，按体重缩放、朝向中心布局，叠加纹理纸张背景后打包为单页。空状态显示光秃栖枝。
• 输出层：双通道并行——Inky Impression 电子墨水屏（推荐）与 Web Kiosk（:8080）。管理界面位于 :8080/admin。
• 数据持久化：所有配置、缓存与日志存储于 /data 卷，容器化部署时通过 -v fugleramme:/data 挂载。

这种解耦使 Fugleramme 可灵活适配不同硬件：无电子墨水屏时纯 Web 运行；已有 BirdNET-Go 实例时零配置接入；开发阶段可用 fugleramme-fake-detector 模拟检测数据。

艺术资产：手工策展的公共领域遗产

项目一半价值在于对历史科学插图的活化利用：

• 来源可靠：所有图版取自斯堪的纳维亚、英国及中欧出版的 19 世纪自然史著作，属公共领域。
• 人工精修：每张插图经手动去背、色彩校正与细节修复（部分使用 AI 辅助修饰，但主体绝非生成式 AI 产物）。
• 布局算法： detected 物种按体重动态缩放，较大鸟类居中，营造视觉平衡；多物种共存时自动排版避免重叠。
• 地域局限：当前覆盖集中于欧洲北部，北美及其他地区物种正在扩充中。完整支持列表可在线搜索，新增艺术需遵循 Adding artwork 流程。

部署方式：从开发到生产的全路径支持

本地开发

uv sync                                       # 创建虚拟环境
uv run fugleramme-fake-detector               # 启动模拟检测器 (:8090)
uv run fugleramme-dev                         # 启动热重载服务 (:8080)

Raspberry Pi 一键安装

curl -fsSL https://raw.githubusercontent.com/arnegiacomo/fugleramme/main/install.sh | bash

脚本自动克隆仓库、安装依赖、配置 systemd 服务。全新系统建议安装后重启。空白 SD 卡用户参阅完整安装指南。

容器化部署

# 拉取预构建镜像
docker run -d -p 8080:8080 -v fugleramme:/data \
  -e FUGLERAMME_DETECTOR_URL=http://birdnet.local:8080 \
  ghcr.io/arnegiacomo/fugleramme

# 或本地构建
docker build -t fugleramme .
docker run --rm -p 8080:8080 -v fugleramme:/data \
  -e FUGLERAMME_DETECTOR_URL=http://birdnet.local:8080 fugleramme

带 USB 麦克风的 Linux 主机可使用 docker-compose 同时启动 BirdNET-Go 与 Fugleramme：

curl -fsSL .../examples/docker-compose.yml -o docker-compose.yml
docker compose up -d

硬件要求与替代方案

• 推荐配置：Raspberry Pi 5 + Inky Impression 13.3″ (Spectra 6) + USB 麦克风 + A4 相框
• 最低可行：Pi 4 + 任意兼容麦克风 + Web Kiosk（HDMI 或远程浏览器）
• 电子墨水非必需：无屏时仅损失低功耗与纸质质感，功能完整保留
• 详细清单：参见 Hardware 文档，含替代型号与采购建议