release: v0.8.10 修复瀑布流抖动与媒体尺寸元数据

Author: ChanMo

docs/release_notes.md

@@ -3,6 +3,15 @@
 ## Unreleased
 - 待补充
 
+## v0.8.10 (2026-02-22)
+- 修复 Library/Favorites 的 Quick Viewer 关闭后页面滚动锁死问题：补齐 body 滚动状态恢复逻辑，确保关闭弹层后列表可继续滚动。
+- Library API 增强媒体尺寸返回：`/api/library/items` 新增 `width` / `height` 字段，并在 `~/.tiklocal/metadata.json` 统一缓存图片与视频尺寸信息。
+- 尺寸探测策略优化：图片使用 Pillow 读取，视频使用 ffprobe 读取；缓存命中后直接复用，减少重复探测开销。
+- 修复图片 AI 元数据写入覆盖风险：生成标题/标签时改为 merge 写回，保留 `media_meta` 等已有字段。
+- Library/Favorites 瀑布流渲染升级为固定列最短列分发引擎，替代 CSS 多列自动流，降低滚动加载时右侧列反复跳动与回流重排。
+- 新增瀑布流响应式重排策略：仅在窗口变化时防抖重排，保持无限加载与 Quick Viewer 索引一致性。
+- 更新 `tests/test_library_upgrade.py`，补充瀑布流脚本标记与 `width`/`height` 字段断言，覆盖关键回归点。
+
 ## v0.8.9 (2026-02-22)
 - 信息架构升级：底部导航调整为 `Flow / Library / Favorites / Download / Settings`，其中 `Library` 成为视频+图片统一入口，`Favorites` 独立为一级入口。
 - Library 交互重构为极简 Masonry：移除顶部传统筛选表单与卡片冗余文本，仅保留媒体本身的沉浸式浏览。

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "TikLocal"
-version = "0.8.9"
+version = "0.8.10"
 description = "A local media server that combines the features of TikTok and Pinterest"
 authors = ["ChanMo <chan.mo@outlook.com>"]
 readme = "README.md"

tests/test_library_upgrade.py

@@ -47,6 +47,8 @@ def test_library_page_has_mode_tabs_and_no_masonry_label(client):
     assert "id=\"quick-play-status\"" in body
     assert "#quick-view.immersive .quick-caption-panel" in body
     assert "image-focus" not in body
+    assert "waterfall-col" in body
+    assert "scheduleWaterfallRelayout" in body
     assert "flow_ui_shared.js" in body
     assert "flow_state_controller.js" in body
     assert "createFlowStateController(" in body
@@ -73,6 +75,7 @@ def test_api_library_items_supports_modes_and_seed(client):
     all_data = all_res.get_json()
     assert all_data["success"] is True
     all_items = all_data["data"]["items"]
+    assert all("width" in item and "height" in item for item in all_items)
     assert any(item["type"] == "video" for item in all_items)
     assert any(item["type"] == "image" for item in all_items)
 

tiklocal/app.py

@@ -3,11 +3,13 @@
 import json
 import random
 import datetime
+import subprocess as sp
 from urllib.parse import quote, unquote
 from importlib.metadata import version, PackageNotFoundError
 from pathlib import Path
 
 from flask import Flask, render_template, send_from_directory, request, redirect, send_file
+from PIL import Image
 
 # Service Imports
 from tiklocal.services import LibraryService, FavoriteService, RecommendService, IMAGE_EXTENSIONS
@@ -272,9 +274,88 @@ def _collect_library_records(*, favorites_only: bool = False) -> list[dict]:
         records.sort(key=lambda item: (item['mtime_ts'], item['name']), reverse=True)
         return records
 
+    def _read_media_dims_from_metadata(name: str) -> tuple[int | None, int | None]:
+        payload = metadata_store.get(name)
+        if not isinstance(payload, dict):
+            return None, None
+        media_meta = payload.get('media_meta')
+        if not isinstance(media_meta, dict):
+            return None, None
+        try:
+            width = int(media_meta.get('width') or 0)
+            height = int(media_meta.get('height') or 0)
+        except (TypeError, ValueError):
+            return None, None
+        if width <= 0 or height <= 0:
+            return None, None
+        return width, height
+
+    def _save_media_dims_to_metadata(name: str, media_type: str, width: int, height: int) -> None:
+        if width <= 0 or height <= 0:
+            return
+        current = metadata_store.get(name)
+        payload = dict(current) if isinstance(current, dict) else {}
+        payload['media_meta'] = {
+            'type': media_type,
+            'width': int(width),
+            'height': int(height),
+            'updated_at': datetime.datetime.utcnow().isoformat() + 'Z',
+        }
+        metadata_store.set(name, payload, overwrite=True)
+
+    def _probe_media_dims(name: str, media_type: str) -> tuple[int | None, int | None]:
+        target = library_service.resolve_path(name)
+        if not target or not target.exists():
+            return None, None
+
+        if media_type == 'image':
+            try:
+                with Image.open(target) as img:
+                    width, height = img.size
+                if int(width) > 0 and int(height) > 0:
+                    return int(width), int(height)
+            except Exception:
+                return None, None
+            return None, None
+
+        try:
+            cmd = [
+                'ffprobe',
+                '-v', 'error',
+                '-select_streams', 'v:0',
+                '-show_entries', 'stream=width,height',
+                '-of', 'json',
+                str(target),
+            ]
+            proc = sp.run(cmd, capture_output=True, text=True, timeout=8)
+            if proc.returncode != 0:
+                return None, None
+            payload = json.loads(proc.stdout or '{}')
+            streams = payload.get('streams') or []
+            if not streams:
+                return None, None
+            stream = streams[0] if isinstance(streams[0], dict) else {}
+            width = int(stream.get('width') or 0)
+            height = int(stream.get('height') or 0)
+            if width > 0 and height > 0:
+                return width, height
+        except Exception:
+            return None, None
+        return None, None
+
+    def _get_or_probe_media_dims(name: str, media_type: str) -> tuple[int | None, int | None]:
+        width, height = _read_media_dims_from_metadata(name)
+        if width and height:
+            return width, height
+        width, height = _probe_media_dims(name, media_type)
+        if width and height:
+            _save_media_dims_to_metadata(name, media_type, width, height)
+        return width, height
+
     def _serialize_library_item(record: dict) -> dict:
         name = str(record.get('name') or '')
         media_type = str(record.get('media_type') or 'video')
+        width, height = _get_or_probe_media_dims(name, media_type)
         encoded = quote(name)
         media_url = f"/media?uri={encoded}"
         return {
@@ -285,6 +366,8 @@ def _serialize_library_item(record: dict) -> dict:
             'thumb_url': media_url if media_type == 'image' else f"/thumb?uri={encoded}",
             'mtime_ts': float(record.get('mtime_ts') or 0),
             'size_bytes': int(record.get('size_bytes') or 0),
+            'width': int(width) if width else None,
+            'height': int(height) if height else None,
         }
 
     def _apply_library_mode(records: list[dict], *, mode: str, min_mb: int, seed: str) -> list[dict]:
@@ -895,8 +978,10 @@ def api_image_metadata():
             result['prompt_source'] = prompt_source
             result['llm_source'] = llm_source
             result.setdefault('prompt_hash', compute_prompt_hash(effective_prompt))
-            metadata_store.set(uri, result, overwrite=True)
-            return {'success': True, 'data': result}
+            merged = dict(existing) if isinstance(existing, dict) else {}
+            merged.update(result)
+            metadata_store.set(uri, merged, overwrite=True)
+            return {'success': True, 'data': merged}
         except Exception as e:
             return {'success': False, 'error': str(e)}, 500