FoloToy-Gallery

FoloToy-Gallery 是运行在 FoloToy AI Passport 上的离线彩色电子相册固件。手机连接设备热点后，可以用浏览器上传、预览和删除照片、GIF 动图、实况图和背景音乐；设备端用三颗实体按键浏览内容、开启轮播、控制音乐、调整亮度和息屏时间。

当前版本：V1.4.0
开发者：PhoenixZHC
目标硬件：FoloToy AI Passport

功能介绍

把手机里的照片、GIF 动图、实况图和音乐带到 AI Passport 小屏上。设备开机后会创建一个无密码热点，手机连上后打开 http://192.168.4.1/，选择文件并上传；照片和动图会在手机浏览器中转换为屏幕格式，音乐会转换为设备专用 FAM1 文件后再传给设备。设备端支持按键切换、动图播放、背景音乐、轮播、删除和设置。

手机上传：连接 FoloToy-Gallery-XXXX 热点，浏览器打开 http://192.168.4.1/ 上传照片、GIF 或实况图。
全屏相册：照片和 GIF 都会铺满 240x320 屏幕，GIF 最高按 10 帧/秒播放。
背景音乐：网页选择 MP3/M4A/WAV 等浏览器可解码音频，本地转为 12 kHz 或 8 kHz 单声道 FAM1 后上传，设备不保存原始 MP3。
按键控制：上键下一张，下键上一张，OK 键开启或暂停轮播；长按 OK 进入设置并打开“音乐播放”，即可在设备上播放、暂停和切歌。
网页管理：网页只负责照片、动图和歌曲的上传、查看与删除，不承担音乐播放控制。
设备设置：长按 OK 进入设置，可打开音乐播放页，并调整亮度、息屏、轮播间隔、音乐音量、播放模式和息屏播放。

使用方式

烧录固件并启动设备。
手机连接设备热点，名称类似 FoloToy-Gallery-AF80，无密码。
建议使用 Chrome 浏览器打开 http://192.168.4.1/。
点击“选择照片、GIF 或实况图”，选择一个或多个文件，再点击“上传”。
GIF、实况图和音乐会先在手机中转换，上传完成后设备自动刷新列表。
播放音乐时，长按设备 OK 键进入设置，选择“音乐播放”。

说明：设备按真实剩余空间判断能否继续上传。网页会显示容量已用百分比；如果转换后的文件大于剩余可用空间，上传会被拒绝。

动图限制：GIF 原文件不超过 10 MB；实况图原文件不超过 60 MB。设备保存的动图最长 10 秒、最多 100 帧、转换后不超过 2.5 MB。转换会优先使用 10 帧/秒，文件过大时自动降低到能保存的最高帧率。音频不会保留。Android Motion Photo 会尝试自动提取内嵌视频；iPhone 相册不能在网页里直接选出实况视频，请先“存储为视频”后上传 MOV/MP4，也可以上传 .livp 或同时选择同名照片和 MOV/MP4。

音乐限制：原始音频不超过 30 MB，单首最长 6 分钟，转换后的 FAM1 文件不超过 2.5 MB。默认使用 12 kHz 单声道；空间不足时网页会在压缩前自动改用 8 kHz。原始音频只在手机浏览器本地解码，不上传云端，也不保存到设备。

按键操作

场景	上键	下键	OK 键
浏览照片或 GIF	下一项	上一项	开启或暂停轮播
音乐播放页	上一首	下一首	播放或暂停音乐
相册页双击快捷操作	下一首	上一首	播放或暂停音乐
设置菜单	上移或调大	下移或调小	进入、确认或打开关于

设置项包括电量、亮度、息屏时间、轮播间隔、存储容量、音乐播放、音乐音量、音乐模式、息屏播放、关于和返回。音乐播放页中，上键上一首、下键下一首、OK 播放或暂停、长按 OK 返回相册。轮播间隔可选 5S、10S、15S、30S、1M、5M 和 15M。

项目结构

components/bsp/          板级支持包：屏幕、按键、电池、音频、I2C
main/                    相册应用：显示、动图播放、设置、媒体存储、热点和网页服务
main/web_ui.html         手机端上传和管理页面源码
main/live_photo_to_fga.js 实况图提取、视频抽帧和 FGA1 转换
main/audio_adpcm.js      浏览器端音频重采样、IMA ADPCM 编码和 FAM1 打包
main/web_ui.h            由 gen_web_ui.py 生成的 gzip 内嵌网页
tests/                   主机端逻辑测试和屏幕渲染测试
partitions.csv           8 MB Flash 分区表，含 photos 数据分区
sdkconfig.defaults       ESP32-C3、USB 控制台、Wi-Fi 和内存配置
ARCHITECTURE.md          当前实现架构说明
玩法介绍.md             面向展示和分享的玩法介绍
CONTEXT.md               当前进度、验证结果和未验证事项

构建与烧录

当前完整固件为 release/FoloToy-Gallery-V1.4.0-8MB-full.bin，可使用 FoloToy AI Passport 官方网页刷入工具刷入设备。

该固件固定为 8,388,608 字节，包含引导程序、分区表、主程序和全部数据分区的初始状态。SHA-256：3ABB247B222A0D4C01BB06129F49F45B590D7378A8FFD44D4CF16104246A9121。

这是整机镜像，刷入会覆盖整块 Flash，设备中已有的照片、动图、音乐和设置都会被清空。

注意事项

设备热点当前无密码，并且只允许 1 台设备连接，避免 ESP32-C3 的 Wi-Fi 和 HTTP 内存压力过高。
上传文件会在手机浏览器里离线裁剪或转换，原图、GIF、实况视频和原始音乐不会上传到云端。
建议使用 Chrome 浏览器进行上传、预览和删除操作。

开发参考记录

2026-08-24，GIF 实现：设备网页运行在普通 HTTP 地址，不能依赖要求安全上下文的 WebCodecs ImageDecoder；网页端离线内嵌 MIT 许可的 deanm/omggif，固定提交为 0ec9069a525ec66223eadda3d62059d3685fd3b0，文件 SHA-256 为 DD4223A83BB9424DE82861BB045D0480D41E9EE43F160E84B42D99952E3C44EF。设备端只解析自有且严格校验的 FGA1 格式。
2026-08-24，实况图实现：网页端按文件内容提取 Android Motion Photo 或 .livp/同名 MOV 的短视频，用浏览器 <video> 和 Canvas 抽帧后复用 FGA1 编码；设备端不解析 HEIC、MOV 或 MP4。

电子相册

关于