Media Server
& Smart Streaming

1.1 What is XteVision Media Server?

XteVision Media Server (xtevision-media-server v1.0.0) is a local video streaming server that delivers films and video files from a directory tree over the network. It offers a modern web UI for browsing, filtering, and playing videos in any browser — without additional software installation on the client. It is designed to be re-branded and run by any company.

1.2 Key Capabilities

• Browser-based media library: all videos as a grid with thumbnails
• Folder categorization: projects/customers as filter buttons
• Smart streaming: automatic H.264 transcoding for unsupported codecs
• Thumbnail generation: automatically extracted from each video file
• Multi-language: English, Deutsch, 中文
• Dark/Light mode: toggleable design
• Playlist function: automatic playback of the next video

1.3 Target Users

• Primary: Companies that need to stream internal/production videos (project footage, customer recordings, training content) over a LAN to any browser
• Secondary: Any organization wanting a self-hosted, no-client video library with smart codec fallback

2.1 High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Browser (any modern browser)              │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────────────────────┐  │
│  │ Video    │ │ Category │ │ Video Player (HTML5 modal)         │  │
│  │ Grid     │ │ Filters  │ │ + Smart Codec Fallback             │  │
│  └──────────┘ └──────────┘ └──────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTP/REST API
┌──────────────────────────────┴──────────────────────────────────┐
│                    Node.js Server — Express.js (port 5002)        │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌──────────────────┐  │
│  │ /videos   │ │ /thumbnail│ │ /video/   │ │ FFmpeg (transcode) │  │
│  │ (list)    │ │ (JPEG)    │ │ original  │ │ H.264 + AAC        │  │
│  │           │ │           │ │ /h264     │ │                    │  │
│  └───────────┘ └───────────┘ └───────────┘ └──────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────┴──────────────────────────────────┐
│                    Filesystem (source of truth)                   │
│  video/  →  folder tree (categories)                              │
│  .cache/ →  h264/ + thumbnails/                                 │
└───────────────────────────────────────────────────────────────────┘

2.2 Communication Flow

1. Browser → Server: GET /videos lists all files; GET /thumbnail/... fetches JPEGs; GET /video/original/... and GET /video/h264/... stream media
2. Server → Filesystem: readdirSync() reads the video/ tree on every /videos call
3. Server → FFmpeg: Thumbnails and H.264 transcodes are generated on demand, then cached

2.3 Deployment Model

XteVision Media Server is designed for self-hosted, LAN-only operation:

• Runs as a standalone Node.js server on your own hardware
• No database — the filesystem is the source of truth
• No authentication — designed for local LAN use
• FFmpeg is embedded via ffmpeg-static

4.1 Prerequisites

• Node.js v18 or higher
• NPM (installed with Node.js)

4.2 Install

# 1. Switch to the project directory
cd /path/to/video_server

# 2. Install dependencies
npm install

The following packages are installed:

4.3 Start the Server

npm start
# or: node server.js

The server then runs on http://localhost:5002. Console output on successful start:

Using ffmpeg: /path/to/ffmpeg-static
Video server running at http://localhost:5002

4.4 Run in the Background (Linux/macOS)

nohup node server.js > server.log 2>&1 &

5.1 Video Directory

All videos live in the video/ folder in the project directory. The structure is organized by customer/project:

video/
├── Anting/
│   ├── anting.mp4
│   ├── biergarten720p.m4v
│   └── tiky_xuyun720p50.mp4
├── Porsche_VW/
├── Deutsche-Schule/
├── prodigy/
│   ├── prodigy_cn.mp4
│   ├── prodigy_de.mp4
│   └── prodigy_en.mp4
└── ...

5.2 Adding New Videos

1. Copy the video file to the desired subfolder of video/
2. Reload the web page — the server rescans the directory on every /videos call

5.3 Supported Formats

6.1 Layout

The web UI at http://localhost:5002 is divided into three areas:

• Header: title line, language dropdown (English / Deutsch / 中文, saved in localStorage), and a theme toggle (dark/light)
• Categories (folder buttons): all found subfolders as filter buttons; "All" shows every video
• Video grid: grid view with thumbnail, title, folder name, and a play-button overlay

6.2 Video Player (Modal)

Clicking a video opens an overlay player:

• HTML5 video player with controls (play/pause, volume, fullscreen, timeline)
• Playlist — all videos of the current category as a list; automatic jump to the next video
• Close — click × or press Esc

6.3 Smart Codec Fallback

The player automatically detects whether the browser can play the video natively:

1. Check HEVC/H.265 support → if yes, stream the original file
2. No HEVC support → switch immediately to H.264 transcoding
3. Playback error → automatic fallback to H.264
4. No video stream detected → switch to H.264

7.1 Endpoints

7.2 Examples

# List all videos
curl http://localhost:5002/videos

# Get a thumbnail
curl http://localhost:5002/thumbnail/Anting/anting.mp4

# Stream the original (with range support)
curl http://localhost:5002/video/original/Anting/anting.mp4

# Stream an H.264-transcoded version
curl http://localhost:5002/video/h264/Anting/anting.mp4

[
  "Anting/anting.mp4",
  "Anting/biergarten720p.m4v",
  "prodigy/prodigy_cn.mp4"
]

8.1 H.264 Streaming

When a video cannot be played natively, the server automatically transcodes it to H.264 + AAC — the format every modern browser can play.

8.2 Thumbnails

• Frame position: 2 seconds after video start
• Resolution: 480px width, proportional height
• Quality: JPEG quality 2 (high quality)
• Timeout: 30 seconds per thumbnail

To relieve the server, thumbnail generations are queued and concurrent requests for the same thumbnail are deduplicated. Generated thumbnails live in .cache/thumbnails/ and are served directly for 24 hours (Cache-Control: public, max-age=86400).

8.3 Cache Management

.cache/
├── h264/          # H.264-transcoded videos
└── thumbnails/    # JPEG thumbnails

Both directories mirror the folder structure of video/. To clear the cache (e.g. after changes to the original files):

# Delete cache subdirectories
rm -rf .cache/h264/* .cache/thumbnails/*

# Or delete the whole cache folder
rm -rf .cache

9.1 Server Won't Start

• Port already in use: Check with lsof -i :5002, then kill the process (kill -9 [PID]).
• FFmpeg error: Using ffmpeg: undefined means ffmpeg-static is not installed correctly — run npm install ffmpeg-static.

9.2 Video Not Playing

• Black screen in player: The browser does not support the codec. The server should fall back to H.264 automatically — verify the .cache/h264/ folder is writable.
• "Video not found" (404): Verify the file exists in video/. Filenames with special characters are expected URL-encoded.

9.3 Thumbnail Not Showing

• "Thumbnail generation failed" (500): FFmpeg cannot read the video → the file may be corrupt. Verify .cache/thumbnails/ is writable.
• Thumbnail is black: The video may have no video stream at 2 seconds (e.g. very short videos). The server defaults to the frame at 2 seconds (-ss 2).

9.4 Transcoding Takes Too Long

• Large videos (multiple GB) need time for H.264 transcoding — this is normal. The first request blocks until transcoding completes; all subsequent calls are immediate.