v0.5.0

v0.5.0

新增

• TrimUI Smart Pro 移植(bata)（packaging/trimui/、scripts/package_trimui.py）：
  • 新增 TrimUI 媒体源，自动发现 TrimUI 自己的封面图；
  • 新增 TrimUI 按键映射，可用环境变量选择；
  • 补齐中文字体候选目录，TrimUI 上中文不再显示为方块；
  • 启动器支持直接调用 RetroArch 时指定配置文件路径。
• 按键音效：移动 / 确认 / 返回三种提示音，由 ALSA 合成（不随包附带音频文件）。
  设置菜单新增「按键音效」开关与「按键音量」；两个音量行边调边听，
  不必等按 A 提交。机身音量键现在同时调预览音量与按键音量，两者的差值保持不变。
• 游戏描述滚动跑马灯：副屏（及单屏详情条）放不下的简介改为横向滚动，
  不再被截断在半句话上；只有真正超宽的简介才会滚动。

优化

• 封面空闲预热：进入某个平台后，只要停手 0.35 秒，后台就开始按一整套
  （轮播 4 档 + 网格 + 列表 + 详情条 + 两档 Logo，共 8 张）把整个平台的封面
  生成好；一按键立刻让路，停下继续。一个源只解码一次派生全部尺寸，
  实测单游戏 4 尺寸 103 ms（原来逐个请求约 300 ms）。
• 首页预热：平台选择页同样空闲预热 —— 每个平台的背景 / Logo（原先只有 32 项
  内存缓存，63 个平台滚一圈就被挤掉，滚回来要重新解码）以及预览条的 6 张封面。
• 缓存进度显示：游戏数量旁边显示「531 · 缓存 85」，按游戏个数统计，
  一个游戏的一整套都齐全才计入；三个视图共用同一套缓存，切换视图数字不再跳变。
• 变体系统目录（FBNEO ACT 等）在平台卡片上显示变体徽章，便于区分。

修复

• 游戏退出后预览失效：退出游戏回到前端后视频预览不再出画面，
  某些情况下还会导致界面崩溃。修了 ffmpeg 运行环境探测（兼容设备自带的编解码库）
  与声卡释放 / 重开的时序。
• 平台图的内存缓存上限 32 → 256，滚出再滚回不再重复解码。

---

Added

• TrimUI Smart Pro port(bata) (packaging/trimui/, scripts/package_trimui.py):
  • a TrimUI media source that finds the cover art TrimUI ships itself;
  • a TrimUI key map, selectable through an environment variable;
  • extra font candidate directories, so Chinese stops rendering as boxes;
  • the launcher can now be given a RetroArch config path.
• Button sounds: move / confirm / back, synthesised through ALSA (no audio
  files in the bundle). The settings menu gains a "button sound" switch and a
  "button volume" row; both volume rows are applied as you move them
  instead of waiting for A. The volume rocker now moves both the preview
  volume and the button volume, keeping the gap between them.
• Scrolling descriptions: a blurb that does not fit the bottom panel (or
  the single-screen strip) scrolls sideways instead of being cut off
  mid-sentence. Only a blurb that actually overflows scrolls.

Improved

• Idle cover warm-up: once a list has stood still for 0.35 s, the whole
  platform is warmed in the background as one complete set per game (the
  four carousel sizes, the grid, the list, the detail strip and two logos —
  eight files). Any input puts the warm-up aside and it resumes where it left
  off. One source is decoded once for every size: 103 ms for four sizes
  against ~300 ms the old way.
• Home page warm-up: the platform picker warms its own artwork too — each
  platform's background and logo (its cache held 32 items, so a 63-platform
  library evicted a card before you scrolled back to it) plus the six preview
  covers.
• Progress readout: the game count now reads "531 · 85 cached", counted in
  games — a game counts once its whole set is on the card. All three views
  share one set, so switching views no longer makes the number drop.
• Variant system directories (FBNEO ACT and friends) show a variant badge on
  their card.

Fixed

• Preview dead after a game: coming back from a game, clips no longer
  played at all and the UI could crash. Fixed the ffmpeg environment probe
  (it must cope with the codecs the firmware ships) and the order in which the
  sound card is released and taken back.
• The platform art cache holds 256 entries instead of 32, so scrolling away and
  back no longer re-decodes a card.

---

v0.4.0

更新日志

v0.4.0

新增

• 开机自启动：设置菜单新增「开机启动」开关。打开后设备通电即进入 Retrostation，不必再从
  APPS 菜单点一次。
• 系统电源操作：退出对话框改为三项可选 —— 退出 / 重启 / 关机（上下键选择，A 确认）。
  其中重启与关机是系统级操作，不再只能退回官方菜单。
• 启动过渡动画：启动游戏时先显示「正在启动《游戏名》」并带转圈动画，随后才交给模拟器。
  在此之前画面会停在前一帧（或黑屏）几秒，看起来像卡死。
• 全局搜索显示所属平台：在总览（ALL）里搜索时，每条结果的第二行标出它属于哪个平台，
  同名游戏（如多个版本的同一作品）不再分不清。

修复

• 带变体后缀的系统目录无法识别：FBNEO ACT、GBA Hank、MAME ACT 这类
  <系统> <变体> 的目录名在系统表里查不到，封面、Logo 和启动核心全部落空。
  现在统一回退到首词对应的基系统 —— FBNEO ACT→fbneo、GBA Hank→gba、
  MAME ACT→mame，图能显示、游戏能启动。
• 用户分区只读时前端崩溃：分区被内核以只读挂载时（如 errors=remount-ro），
  保存配置与续玩状态会抛出 OSError 并带崩整个前端。现在这两处改为只记告警并继续，
  游戏照常启动（启动命令走 /tmp，不受影响）。
• 无图平台显示为空白块：某个平台连封面和 Logo 都没有时，占位图上会写上平台名，
  不再是一块认不出来的空白。

优化

• 列表滚动的渲染性能（减少每帧重复绘制）。

文档

• README 补充 APPS 菜单的安装说明（中英文）。

---

Added

• Launch on boot: new "开机启动 / Autostart" switch in the settings menu
  (START). When enabled the device boots straight into Retrostation instead of
  the stock menu.
• System power actions: the exit dialog now offers three choices —
  Quit / Reboot / Power off (Up/Down to pick, A to confirm). Reboot and
  power off are real system operations.
• Launch transition: starting a game now shows a "正在启动《name》" splash
  with a spinner before handing over to the emulator. Previously the screen
  froze on the last UI frame (or went black) for a couple of seconds, which
  looked like a hang.
• Search shows the platform: when searching from the ALL overview, each hit
  gets a second line naming the platform it belongs to, so entries that share a
  title can be told apart.

Fixed

• System directories with a variant suffix were unrecognised: folders such
  as FBNEO ACT, GBA Hank or MAME ACT — a <system> <variant> name — are
  absent from the system table, so their cover, logo and launch core all came
  up empty. They now fall back to the base system named by the first word:
  FBNEO ACT → fbneo, GBA Hank → gba, MAME ACT → mame. Artwork shows
  and the game launches.
• Frontend crashed on a read-only user partition: when the kernel mounts the
  user partition read-only (e.g. errors=remount-ro), saving the config and the
  resume state raised OSError and took the whole frontend down. Both are now
  best-effort: a warning is logged and the launch continues (the launch command
  itself goes to /tmp, which stays writable).
• Platforms without artwork rendered as a blank tile: when a platform ships
  neither a cover nor a logo, its name is now drawn onto the placeholder
  instead of leaving an unidentifiable blank.

Improved

• List scrolling render performance (fewer redundant repaints per frame).

Docs

• README: added the APPS-menu installation instructions (Chinese and English).

v0.3.0

v0.3.0

新增

• 设置菜单（按 START 打开，位于底部）新增两项：
  • 「缩略图缓存」：开关。关闭后不再读写任何缓存文件，封面改为实时缩放（桌面端每图约 5–10 ms，掌机建议保持开启）。
  • 「清空图片缓存」：删除卡上所有 .cache 目录回收空间，完成后提示清理的文件数量。
• 启动后的后台扫描顺带清理失效缓存条目（封面已更换、旧版本残留），不再永久占用存储。

修复

• 副屏视频完全无画面（H700）：修复固件 fontconfig 软链失效与精简版 libavformat 缺 rawvideo 的问题；启动器启动时自动修复链接，解码器改用干净运行环境。
• 换封面后仍显示旧缩略图：缓存文件名加入文件修改时间，换图立即生效。
• 封面透明通道丢失：网格与轮播中的透明 PNG 保持透明。
• 桌面端封面只占格子中间一小块：等比缩放允许放大，小封面撑满格子。
• 半截缓存文件导致崩溃：改为原子写入（先写临时文件再改名）；清理时文件被占用不再中断绘制。
• ffprobe 探测挡住首帧：探测移至首帧之后、独立线程执行，不再误判拉黑视频。
• 音频重试挡住解码线程：音频改在后台线程启动；修复切换游戏时音频泄漏、模拟器启动后继续响的问题。
• ffmpeg 可用性检测过粗：由 which ffmpeg 改为实际执行版本探测。

外观

• 网格与轮播改为等比完整显示：封面按自身比例居中取最大尺寸，GBA（方）、FC（横）、MD（纵）封面均完整展示。
• 去掉网格卡片常驻边框与底板，选中项保留高亮描边；轮播卡片不再有底板。

其他

• 缩略图编码质量 86 → 80，体积减少约 25%。
• 解码器出错时，将 ffmpeg 报错原文、实际执行命令、解析到的二进制与 muxer 数量写入 log.txt。
• 文档新增「缩略图缓存」「副屏视频不出画面」两节（中英文）。

v0.3.0

What's New

• Two new items added to the Settings menu (press START, at the bottom):
  • Thumbnail Cache: toggle. When off, no cache files are read or written; covers are scaled in real time (~5–10 ms per cover on desktop; keep it enabled on handhelds).
  • Clear Image Cache: deletes all .cache directories on the card to reclaim space, and reports how many files were removed.
• The background scan after startup also cleans up stale cache entries (covers replaced, leftovers from old versions), so unrecognized cache files no longer occupy the card permanently.

Fixes

• Second-screen video shows no picture at all (H700): caused by two stacked firmware issues — the fontconfig symlink reverting to an old version on every reboot (missing FcWeightFromOpenTypeDouble, so ffmpeg dies with a symbol lookup error), and the private library path supplying a stripped libavformat with only 10 audio muxers and no rawvideo. The launcher now checks and repairs the fontconfig link at startup (only when the symbol is actually missing), and the decoder runs in a clean environment. See USAGE §14.
• Stale thumbnail after cover replacement: the cache filename now includes the file's modification time, so changes take effect immediately.
• Transparent channel lost on covers: transparent PNGs stay transparent in the grid and carousel instead of being flattened onto a gray background.
• Desktop covers only occupied a small area in the middle of the cell: proportional scaling now allows upscaling, so small covers fill the cell.
• Partial cache file caused a crash: thumbnails are now written atomically (temp file first, then rename); cleanup no longer throws and aborts rendering when a file is locked (common on Windows).
• ffprobe probe blocked the first frame: probing took ~4.8 s, exceeding the 3 s hang threshold, so videos were permanently blacklisted. The probe now runs in a separate thread after the first frame.
• Audio retry blocked the decoder thread: audio retries took 0.7 s when the sound card was busy and used to run before decoding. Audio now starts on a background thread; also fixed audio leaking when switching games and continuing to play after the emulator starts.
• ffmpeg availability check was too coarse: previously only ran which ffmpeg, so a broken binary was relaunched repeatedly. It now actually executes a version probe.

Visual

• Grid and carousel now display covers in full with aspect ratio preserved: covers are no longer cropped, but scaled to the largest size and centered by their own ratio. Cell size stays the same; square (GBA), landscape (FC) and portrait (MD) covers all display completely.
• Removed the permanent border and backplate from grid cards; the selected item keeps a highlight outline. Carousel cards no longer have a backplate either.

Other

• Thumbnail encoding quality 86 → 80, ~25% smaller file size, no visible difference at thumbnail dimensions.
• When the decoder fails, the raw ffmpeg error message, the actually executed command, the resolved binary and the muxer count are all written to log.txt for self-diagnosis.
• Docs: added "Thumbnail Cache" and "Second-Screen Video Not Displaying" sections (English/中文).

v0.2.1

v0.2.1

中文

新增

• Windows 桌面启动器：支持 tkinter 桌面平台（platform/desktop/）。仅在使用 --desktop 时按需加载，不影响掌机启动。

修复

• 启动：掌机端启动崩溃 —— 桌面平台模块加载时无条件导入 tkinter，掌机 Linux 环境无 tkinter 导致直接启动失败。改为惰性按需导入，掌机运行路径完全不会加载 tkinter。
• 数据解析：Pegasus（天马）格式，单个 game: 块下多条文件（区域 / 版本变体如 asterix.zip、asterixaad.zip…）现已合并为单个游戏条目，元数据关联全部文件；不再将每个文件拆分为不带元数据的独立游戏。

---

English

Added

• Windows desktop launcher with tkinter desktop platform support (platform/desktop/). Loaded on-demand only with --desktop; handheld startup path remains unaffected.

Fixed

• Startup: Handheld startup crash — desktop platform module unconditionally imported tkinter at load time. Since handheld Linux environment lacks tkinter, startup aborted. Now uses lazy on-demand import; handheld code path never touches tkinter.
• Parsing: For Pegasus format, multiple files inside one game: block (region/revision variants e.g. asterix.zip, asterixaad.zip…) are merged into one game entry, metadata applies to all files. No longer split each file into separate metadata-less game entries.

v0.2.0

v0.2.0

一、中文更新日志

主要变更

• 副屏视频带声音：新增 ALSA 音频管线，副屏视频预览可播放音轨，机身音量键直接调节（±5，即时生效）；无视频或解码失败时自动回退展示封面。

• ES-DE 元数据读写与游玩状态互通：gamelist.xml 现支持写回功能，收藏状态、游玩次数、上次游玩时间可与 ES-DE、Batocera 数据互通；设备下屏可标注当前游戏条目对应的真实数据源文件。

• Pegasus / 天马 媒体布局支持：媒体解析模块新增「每游戏一个目录」的资源包格式，支持 media/<游戏名>/boxFront.png、logo.png、background.jpg 等资源路径，与 ES-DE 扁平目录结构互为后备兼容。

• systems.json 自定义核心：支持从配置目录加载自定义 systems.json 文件，可覆盖内置的游戏机种定义，包括机种名称、文件扩展名、模拟器核心等配置，无需修改项目源码。

• 游戏界面动态背景优化：游戏列表、网格视图、轮播页面，均采用当前游戏的 fanart 艺术图做暗化处理后作为页面背景，提升界面视觉效果。

• 前端游戏运行时驻留：启动游戏后，前端程序保持后台驻留，退出游戏后可即时返回原浏览界面，无需重新加载页面。

• 新增真实数据预览脚本：新增 scripts/preview_real.py 脚本，支持调用真实媒体文件与元数据进行无头渲染预览，同时兼容 ES-DE 目录树、Pegasus/天马资源包两种数据源格式。

• 显示渲染问题修复：修复 RGBA 画布 Alpha 通道未压平，导致实体机透明区域显示黑色底色的问题，通过帧上传时强制设定 Alpha 值为255彻底解决该故障。

• 扩充单元测试覆盖范围：新增大量单元测试用例，全面覆盖 ES-DE 布局解析、资源库合并、数据源标注、音视频播放、动态背景渲染等核心功能模块，提升程序稳定性。

部署与兼容说明

直接重新部署即可完成版本更新，用户现有配置文件与 gamelist.xml 文件均完全向后兼容，无需手动迁移数据。项目版本号现已统一由 src/retrostation/__init__.py 文件中的 __version__ 变量单一管控，后续版本迭代仅需修改该文件即可，简化发版流程。

二、English Changelog

Major Changes

• Secondary Screen Video with Audio Support: Added the ALSA audio pipeline to enable audio playback for secondary screen video preview. The physical volume keys adjust the volume in steps of 5 with immediate effect. The system automatically falls back to the cover image if no video source is available or video decoding fails.

• ES-DE Metadata Read/Write & Play State Sync: Enabled write-back support for gamelist.xml. Game favorites, play counts and last played time are fully synchronized between ES-DE and Batocera. The lower screen displays the actual source file of the current game entry.

• Pegasus Media Layout Support: Added support for the "one directory per game" media package format, including standard assets such as media/<game-name>/boxFront.png, logo.png and background.jpg. This structure works as an alternative fallback to the flat directory structure adopted by ES-DE.

• Custom Core via systems.json: Users can override the built-in platform definitions (including system names, file extensions and emulator cores) by loading a custom systems.json from the configuration directory, without modifying the source code.

• Dynamic Background for Game UI: Applied darkened game fanart as the background for game list, grid view and carousel pages, optimizing the overall visual presentation and immersion.

• Persistent Frontend Runtime: The frontend remains resident in memory after game launch. Users can instantly return to the original UI interface after exiting the game without reloading.

• Real-data Preview Script: Added scripts/preview_real.py for headless rendering preview with authentic local media files and metadata. It supports two mainstream data sources: ES-DE directory tree and Pegasus media package.

• Display Rendering Fix: Fixed the black background issue of transparent areas on physical devices caused by unflattened alpha channels of RGBA canvases. The problem is completely resolved by forcing the alpha value to 255 during frame uploading.

• Extended Unit Test Coverage: Added a large number of unit tests covering core modules including ES-DE layout parsing, library merging, data source marking, video and audio playback, and dynamic background rendering, improving overall software stability.

Deployment & Compatibility Notes

Simply redeploy the application for version upgrade. All existing user configurations and gamelist.xml files are fully backward compatible with no manual migration required. The project version is now controlled by a single source: the __version__ variable in src/retrostation/__init__.py. Only this file needs to be updated for future releases, streamlining the version iteration process.

v0.1.0

v0.1.0

0.1.0版本发布，支持安伯尼克官方系统，已测试RGDS(Linux)、RG35xxH，详细内容看readme

Version 0.1.0 released. Supports official Ambernic firmware. Tested on RGDS(Linux) and RG35xxH. See readme for details.