kōsen

Streaming at the speed of light. A self-hosted torrent streaming platform with instant playback, HLS transcoding, and a modern Next.js interface — powered by Bun and NGINX.

Note: This project is for educational purposes. Please respect copyright laws in your jurisdiction.

Get the app running in 30 seconds using pre-built Docker images:

1. Clone the repository

   git clone [https://github.com/not3zra/kousen.git](https://github.com/not3zra/kousen.git)
   cd kousen

2. Start all services (pulls pre-built images from Docker Hub)

   docker compose up -d

3. Access the application Open http://localhost:8080

Home Page: Modern, responsive interface built with Tailwind CSS

Video Player: HLS Streaming with automatic subtitle support

• Overview
• Key Features
• Tech Stack
• Architecture
• Installation
• API Documentation
• Configuration
• Contributing
• License

kōsen enables instant video playback from torrent sources through a modern web interface. The application uses NGINX as a reverse proxy to route requests between the Next.js frontend and Bun backend, with built-in FFmpeg transcoding for format compatibility.

🎬 Streaming & Playback

• Instant Streaming: Start watching without waiting for full downloads.
• Smart Transcoding: Automatic HLS conversion for MKV, AVI, and MOV files via FFmpeg.
• Direct Play: Native MP4 streaming for maximum performance.
• Subtitle Support: Auto-extraction of embedded tracks and external SRTs.
• Watch History: Remembers where you left off.
• Demo Mode: One-click demo with Sintel (open source movie).

🏗 Infrastructure

• Unified Proxy: NGINX handles routing, compression, and caching on port 8080.
• Dockerized: Pre-built images on Docker Hub for instant deployment.
• Auto-Cleanup: Intelligent purging of idle torrents (30-min timeout) to save disk space.
• Real-Time: WebSocket integration for live download stats.

🔒 Security

• Auth: JWT-based stateless authentication with HTTP-only cookies.
• Protection: bcrypt password hashing and strict CORS policies.
• Privacy: NGINX header forwarding for accurate IP logging.

Run pre-built images from Docker Hub.

Prerequisites: Docker 20.10+, Docker Compose v2.0+

1. Clone & Run

   git clone [https://github.com/not3zra/kousen.git](https://github.com/not3zra/kousen.git)
   cd kousen
   docker compose up -d

2. Access Open http://localhost:8080 and click "demo video" to try it out!

For local development where you want to edit code.

Prerequisites: Docker 20.10+, Docker Compose v2.0+

1. Clone the repository

   git clone [https://github.com/not3zra/kousen.git](https://github.com/not3zra/kousen.git)
   cd kousen/app/docker

2. Build & Launch

   docker compose -f docker-compose.dev.yml build
   docker compose -f docker-compose.dev.yml up -d

3. Access Open http://localhost:8080

For native development without Docker.

Prerequisites: Bun 1.0+, Node.js 20+, FFmpeg (in PATH)

1. Backend Setup

   cd backend
   bun install
   bun run db:init
   bun run dev
   # Runs on port 3001

2. Frontend Setup

   cd frontend
   npm install
   npm run dev
   # Runs on port 3000

No torrent on hand? The app includes a one-click demo:

Demo Video: Sintel (Open Source Movie by Blender Foundation)

magnet:?xt=urn:btih:08ada5a7a6183aae1e09d831df6748d566095a10&dn=Sintel

Just click "demo video" on the home page, or paste the magnet link above.

All API requests are routed through NGINX at http://localhost:8080/api/*.

POST /api/torrent/add
Content-Type: application/json

{
  "magnetLink": "magnet:?xt=urn:btih:..."
}

• Direct Stream: GET /stream/:infoHash/:fileIndex
• HLS Playlist: GET /hls/:infoHash/:fileIndex/playlist.m3u8
• Subtitles: GET /captions/:infoHash/:fileIndex

• Port: 8080
• Compression: gzip enabled for text assets.
• Buffering: Disabled for video routes to reduce latency.

Backend (optional .env)

PORT=3001
JWT_SECRET=change_me
TORRENT_DOWNLOAD_PATH=./downloads

Frontend (optional .env.local)

NEXT_PUBLIC_BACKEND_URL=http://localhost:8080

Contributions are welcome! Please check out the issues or submit a PR.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Distributed under the MIT License. See LICENSE for more information.

Pre-built images are available on Docker Hub:

• Backend: docker pull not3zra/kousen-backend:latest
• Frontend: docker pull not3zra/kousen-frontend:latest
• NGINX: docker pull not3zra/kousen-nginx:latest

Or simply use docker compose up -d to pull and run all images automatically.