Video Explorer

Video Explorer is a small local web app for browsing videos from any folder on your machine. It serves a fullscreen-style masonry gallery, lets you sort and filter by filename prefix, and only auto-plays previews for videos that are currently visible on screen.

Features

• Load any local folder by pasting its absolute path into the home page.
• Browse videos in a gapless masonry layout.
• Sort by name, modified time, or file size.
• Filter by starts with and use the custom autocomplete list.
• Toggle bookmarks from the video title overlay and persist them in local SQLite storage.
• Filter the grid to show only bookmarked videos.
• Show file metadata on hover without cluttering the grid.
• Cache detected video aspect ratios in localStorage to reduce layout shifts.
• Serve video files through range-enabled media endpoints for browser seeking.

Supported Video Formats

• .mp4
• .webm
• .ogg
• .mov
• .m4v
• .mkv
• .avi
• .wmv
• .flv

Requirements

• Node.js 22+ recommended
• A modern desktop browser

No external dependencies are required.

Run

npm start

Or:

node server.js

Then open:

http://127.0.0.1:3210

How It Works

1. Enter a local folder path such as C:\Users\username\Videos.
2. The app calls GET /api/videos?folder=....
3. The server scans only the top-level files in that folder, joins bookmark state from data/bookmarks.sqlite, and returns metadata plus media URLs.
4. Bookmark changes are sent to PUT /api/bookmarks.
5. The client renders the result into a masonry grid and lazy-starts preview playback only for visible items.

Configuration

The server supports these environment variables:

• PORT: main app server port. Default is 3210.
• MEDIA_PORTS: comma-separated media server ports. Example: 4001,4002,4003
• MEDIA_SERVER_COUNT: number of media ports to create when MEDIA_PORTS is not set. Default is 32.

If MEDIA_PORTS is not provided, the app starts media servers on sequential ports after the main port. With the default settings, PORT=3210 creates media servers on 3211 through 3242.

API

GET /api/videos

Query parameters:

• folder: absolute folder path

Response shape:

{
  "folder": "C:\\Users\\username\\Videos",
  "count": 2,
  "videos": [
    {
      "name": "clip_001.mp4",
      "relativePath": "clip_001.mp4",
      "extension": ".mp4",
      "size": 1234567,
      "modifiedAt": "2026-03-08T00:00:00.000Z",
      "isBookmarked": false,
      "url": "http://127.0.0.1:3211/api/video?folder=...&file=clip_001.mp4"
    }
  ]
}

PUT /api/bookmarks

Request body:

{
  "folder": "C:\\Users\\username\\Videos",
  "file": "clip_001.mp4",
  "isBookmarked": true
}

Response shape:

{
  "folder": "C:\\Users\\username\\Videos",
  "file": "clip_001.mp4",
  "isBookmarked": true
}

GET /api/video

Query parameters:

• folder: absolute folder path
• file: file name inside that folder

Notes:

• Supports GET and HEAD
• Supports single-range requests for browser seeking
• Returns 404 for missing files and 416 for invalid ranges

Project Structure

.
|-- public/
|   |-- app.js
|   |-- index.html
|   `-- styles.css
|-- server.js
`-- README.md

Notes

• The selected folder path is saved in localStorage under video-explorer:last-folder.
• Video aspect ratios are cached in localStorage under video-explorer:video-ratios.
• Bookmarks are stored on the server in data/bookmarks.sqlite.
• The current implementation does not scan subdirectories recursively.