py-media-server

A simple, lightweight media server for streaming video files over HTTP with a modern web interface.

Features

• 🎬 Stream video files (MP4, MKV, AVI, MOV) from any directory
• ▶️ Full custom player — play/pause, ±10s skip, next/previous, seek bar, volume, playback speed, fullscreen and keyboard shortcuts
• ⏭️ Auto-advance to the next video when one finishes
• 🖼️ Automatic thumbnail generation using FFmpeg
• 📱 Responsive web interface that works on mobile and desktop
• ⚡ Range request support for efficient video streaming
• 🔒 Threaded TCP server for concurrent connections
• 🎨 Modern, dark-themed UI

Installation

From PyPI (when published)

pip install py-media-server

From source

git clone https://github.com/pandiyarajk/py-media-server.git
cd py-media-server
pip install -e .

Requirements

• Python 3.7+
• FFmpeg (optional, for thumbnail generation)

To install FFmpeg:

• Windows: Download from ffmpeg.org or use choco install ffmpeg
• macOS: brew install ffmpeg
• Linux: sudo apt-get install ffmpeg or sudo yum install ffmpeg

Usage

Basic usage

Serve media files from the current directory:

py-media-server

Or specify a directory:

py-media-server /path/to/your/movies

Custom port

py-media-server /path/to/your/movies --port 9000

Custom host and port

py-media-server ~/Videos --host 192.168.1.100 --port 8080

Help

py-media-server --help

Command-line Options

positional arguments:
  directory             Directory containing media files to serve (default: current directory)

optional arguments:
  -h, --help            show this help message and exit
  -p PORT, --port PORT  Port to run the server on (default: 8000)
  --host HOST           Host to bind the server to (default: 0.0.0.0)
  -v, --version         show program's version number and exit

How it Works

1. Start the server: Point it to a directory containing video files
2. Open your browser: Navigate to http://localhost:8000
3. Browse and play: Click on any video thumbnail to start streaming

The server will:

• Scan the directory for supported video formats
• Generate thumbnails automatically (stored in .thumbs subdirectory)
• Serve videos with range request support for smooth playback
• Handle concurrent connections efficiently

Player

Clicking a tile opens the player at /play/<filename>. The page is served with the whole library as its playlist, so next/previous move through the same sorted listing shown on the home page (disabled at the ends).

Controls

Button	Action
⏮	Previous video
⏪	Back 10 seconds
▶ / ⏸	Play / pause
⏩	Forward 10 seconds
⏭	Next video
🔊	Mute, with a volume slider
1x	Playback speed (0.5x – 2x)
⛶	Fullscreen

A draggable seek bar shows elapsed and total time.

Keyboard shortcuts

Key	Action
Space / K	Play / pause
← / →	Seek 10 seconds
↑ / ↓	Volume up / down
N	Next video
P	Previous video
M	Mute
F	Fullscreen

Development

Setup development environment

git clone https://github.com/pandiyarajk/py-media-server.git
cd py-media-server
pip install -e ".[dev]"

Run tests

pytest

Run tests with coverage

pytest --cov=py_media_server --cov-report=html

Project Structure

py-media-server/
├── py_media_server/
│   ├── __init__.py
│   └── server.py
├── tests/
│   ├── __init__.py
│   └── test_server.py
├── setup.py
├── pyproject.toml
├── README.md
├── LICENSE
└── MANIFEST.in

Security Notice

⚠️ Warning: This server is intended for local network use only. It does not include authentication or encryption. Do not expose it to the public internet without proper security measures.

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

0.2.0 (2026-08-15)

• Full custom player: play/pause, ±10s skip, next/previous, seek bar, volume, playback speed, fullscreen, keyboard shortcuts, auto-advance
• Unmatched routes now return 404 instead of closing the connection with no response
• Range requests are clamped to the file size
• Filenames are escaped when embedded in page scripts

0.1.0 (2026-04-19)

• Initial release
• Basic video streaming functionality
• Thumbnail generation
• Web interface
• Command-line interface