From 473b6924976b1cef2114dd5a3a781c394a1ea047 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 26 Nov 2025 12:35:50 +0000 Subject: [PATCH] fix: Address critical issues and add documentation This commit addresses several critical issues identified during code review to make the application runnable and functional. It also adds comprehensive project documentation. Fixes: - Added `backend/requirements.txt` to define Python dependencies. - Added `backend/__init__.py` to resolve module import errors. - Corrected the scanner to store web-accessible URLs in the database instead of raw filesystem paths. - Added a `proxy` configuration to `frontend/package.json` to correctly forward API requests to the backend. - The video streaming endpoint now dynamically determines the MIME type based on the file extension. - Thumbnail filenames are now generated using a unique hash to prevent collisions. - Moved the `media` directory into the `backend` directory to be served correctly. Docs: - Added `AGENTS.md` with detailed information for AI developers. - Added `README.md` with a project overview and setup instructions for human developers. --- AGENTS.md | 62 + README.md | 96 +- backend/__init__.py | 0 backend/database.py | 26 + backend/main.py | 101 + backend/requirements.txt | 5 + backend/scanner.py | 89 + frontend/.gitignore | 23 + frontend/README.md | 70 + frontend/package-lock.json | 17366 ++++++++++++++++++++++++++++++ frontend/package.json | 41 + frontend/public/favicon.ico | Bin 0 -> 3870 bytes frontend/public/index.html | 43 + frontend/public/logo192.png | Bin 0 -> 5347 bytes frontend/public/logo512.png | Bin 0 -> 9664 bytes frontend/public/manifest.json | 25 + frontend/public/robots.txt | 3 + frontend/src/App.css | 57 + frontend/src/App.js | 84 + frontend/src/App.test.js | 8 + frontend/src/Lightbox.css | 54 + frontend/src/Lightbox.js | 44 + frontend/src/index.css | 13 + frontend/src/index.js | 17 + frontend/src/logo.svg | 1 + frontend/src/reportWebVitals.js | 13 + frontend/src/setupTests.js | 5 + 27 files changed, 18244 insertions(+), 2 deletions(-) create mode 100644 AGENTS.md create mode 100644 backend/__init__.py create mode 100644 backend/database.py create mode 100644 backend/main.py create mode 100644 backend/requirements.txt create mode 100644 backend/scanner.py create mode 100644 frontend/.gitignore create mode 100644 frontend/README.md create mode 100644 frontend/package-lock.json create mode 100644 frontend/package.json create mode 100644 frontend/public/favicon.ico create mode 100644 frontend/public/index.html create mode 100644 frontend/public/logo192.png create mode 100644 frontend/public/logo512.png create mode 100644 frontend/public/manifest.json create mode 100644 frontend/public/robots.txt create mode 100644 frontend/src/App.css create mode 100644 frontend/src/App.js create mode 100644 frontend/src/App.test.js create mode 100644 frontend/src/Lightbox.css create mode 100644 frontend/src/Lightbox.js create mode 100644 frontend/src/index.css create mode 100644 frontend/src/index.js create mode 100644 frontend/src/logo.svg create mode 100644 frontend/src/reportWebVitals.js create mode 100644 frontend/src/setupTests.js diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cfcdaeb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,62 @@ +# AGENTS.md + +## Project Overview + +This is the **Local Smart Gallery**, a web application designed to scan, organize, and display a unified timeline of local photo and video files. The goal is to create a seamless browsing experience for media collections. + +## Tech Stack + +- **Backend**: Python with **FastAPI**. + - **Database**: SQLite with **SQLAlchemy**. + - **Video Processing**: **OpenCV** (`cv2`) for thumbnail generation and metadata extraction. + - **Server**: **Uvicorn**. +- **Frontend**: JavaScript with **React**. + - **API Client**: **axios**. + - **Build Tool**: Create React App. + +## Project Structure + +``` +. +├── backend/ +│ ├── venv/ # Python Virtual Environment +│ ├── cache/ +│ │ └── thumbnails/ # Generated video thumbnails +│ ├── database.py # SQLAlchemy models and DB setup +│ ├── main.py # FastAPI application, API endpoints +│ └── scanner.py # Core logic for scanning media files +├── frontend/ +│ ├── public/ +│ └── src/ +│ ├── App.js # Main gallery component +│ ├── Lightbox.js # Modal for viewing single media items +│ ├── App.css +│ └── ... +└── media/ # Default directory for user's media files +``` + +## How to Run Development Servers + +**Important**: The backend and frontend servers must be running concurrently. + +1. **Start Backend Server**: + - Ensure you are in the repository root. + - The Python virtual environment is located at `backend/venv`. + - Run the following command: + ```bash + source backend/venv/bin/activate && uvicorn backend.main:app --host 0.0.0.0 --port 8000 + ``` + +2. **Start Frontend Server**: + - Ensure you are in the repository root. + - Run the following command: + ```bash + cd frontend && npm start + ``` + - The frontend will be available at `http://localhost:3000` and will proxy API requests to the backend at `http://localhost:8000`. + +## Key Logic Points + +- **Scanner**: The `backend/scanner.py` script is the core of the media processing. It iterates through a target directory, identifies images and videos, extracts metadata (`creation_time`, `duration`), and generates thumbnails for videos using OpenCV. All metadata is stored in the SQLite database. +- **Video Streaming**: The `/api/media/stream/{item_id}` endpoint supports HTTP Range Requests (`206 Partial Content`) to ensure large video files can be streamed efficiently without being fully downloaded first. This is crucial for performance. +- **Thumbnails**: Video thumbnails are **not** generated on-the-fly. They are created once during the initial scan and stored in `backend/cache/thumbnails/`. The frontend loads these static thumbnail images for the grid view. \ No newline at end of file diff --git a/README.md b/README.md index f8ca30f..a69a84b 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,94 @@ -# MyOwnPhotoView -view my own local photo +# Local Smart Gallery (支持视频版) + +## 📖 项目简介 (Project Overview) + +Local Smart Gallery 是一个本地智能媒体库,旨在为您混乱的本地照片和视频文件夹带来秩序。它会自动扫描指定目录下的媒体文件,提取元数据,并将它们统一按时间顺序呈现在一个美观、高效的网页界面中。 + +无论是您用相机拍摄的照片,还是手机录制的视频,此应用都会将它们无缝地融合在同一个时间轴上,重现您在特定事件(如漫展、旅行)中的完整回忆。 + +## ✨ 核心功能 (Features) + +- **统一时间线**: 将照片 (`.jpg`, `.png`, `.heic`) 和视频 (`.mp4`, `.mov`, `.avi`) 混合排序在同一个视图中。 +- **视频支持**: + - **自动生成缩略图**: 后端在扫描时使用 OpenCV 截取视频第一帧作为预览,避免前端加载大文件。 + - **流式播放 (Streaming)**: 支持 HTTP Range Requests,即使是几百兆的大视频也能流畅拖动进度条,无需等待完整下载。 + - **元数据提取**: 自动读取视频的创建时间和时长。 +- **高效浏览**: + - **网格视图**: 瀑布流式展示所有媒体,视频文件会以 ▶️ 图标和时长角标进行区分。 + - **详情视图 (Lightbox)**: 点击任意文件可进入大图/播放器模式,支持键盘左右键切换上一个/下一个。 +- **简单的扫描机制**: 通过一个 API 请求即可启动对媒体文件夹的扫描和索引。 + +## 🛠️ 技术栈 (Tech Stack) + +- **后端 (Backend)**: + - **框架**: Python & **FastAPI** + - **数据库**: SQLite & **SQLAlchemy** + - **视频处理**: **OpenCV** (`cv2`) + - **Web 服务器**: **Uvicorn** +- **前端 (Frontend)**: + - **框架**: **React** (via Create React App) + - **HTTP 请求**: **axios** + - **视频播放**: 原生 HTML5 `