videoscroller/README.md

Ticky - Self-Hosted TikTok-Style Video Scroller

A mobile and desktop-friendly infinite scrolling video player built with Python/FastAPI backend and vanilla JavaScript frontend.

Features

• 🎬 Infinite scroll with lazy loading
• 📱 Mobile-friendly swipe navigation
• ⌨️ Keyboard and mouse wheel support
• 🖥️ Responsive design (portrait and landscape)
• 📡 REST API for video management
• 🐳 Docker Compose setup for easy deployment
• ⚡ Fast performance with minimal dependencies

Quick Start

Prerequisites

• Docker and Docker Compose

Setup

1. Place your videos in the videos/ folder:

   cp /path/to/your/videos/*.mp4 ./videos/
   

2. Start the application:

   docker-compose up -d
   

3. Access the app:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:3001/api/videos

Project Structure

ticky/
├── backend/                 # Python/FastAPI backend
│   ├── main.py             # FastAPI application
│   ├── requirements.txt     # Python dependencies
│   ├── Dockerfile          # Backend Docker image
│   └── .dockerignore
├── frontend/               # Vanilla JavaScript frontend
│   ├── index.html          # Main HTML file
│   ├── styles.css          # Responsive styles
│   ├── app.js              # Infinite scroll logic
│   ├── Dockerfile          # Frontend Docker image
│   └── package.json
├── videos/                 # Video storage (volume mount)
└── docker-compose.yml      # Docker Compose configuration

Navigation

Mobile

• Swipe up: Next video
• Swipe down: Previous video

Desktop

• Scroll wheel: Navigate through videos
• Arrow keys: Up/Down navigation
• Space: Next video

API Endpoints

Get Random Videos

GET /api/videos?limit=10

Response:

[
  {
    "id": "unique-id",
    "filename": "video.mp4",
    "url": "/videos/video.mp4",
    "title": "video title"
  }
]

Health Check

GET /api/health

Configuration

Backend Environment Variables

• VIDEOS_DIR: Path to videos directory (default: /videos)
• PORT: Server port (default: 3001)

Supported Video Formats

• MP4
• WebM
• OGG
• MOV
• AVI
• MKV

Performance Optimizations

• Lazy loading: Only current and adjacent videos are rendered
• Preloading: Next video is preloaded for smooth transitions
• Muted autoplay: Videos start muted to allow autoplay
• Efficient DOM: Minimal DOM manipulation for better performance

Customization

Styling

Edit frontend/styles.css to customize:

• Colors and themes
• Control button positions
• Video aspect ratio handling
• Animation speeds

Backend

Modify backend/main.py to:

• Add video metadata (duration, thumbnails)
• Implement video filtering/sorting
• Add authentication
• Cache results

Troubleshooting

No videos loading

• Ensure videos are in the videos/ folder
• Check supported formats (mp4, webm, ogg, mov, avi, mkv)
• Verify permissions: docker exec ticky-backend ls -la /videos

Videos not playing

• Check browser console for CORS errors
• Verify backend is running: curl http://localhost:3001/api/health

Build issues

• Rebuild images: docker-compose down && docker-compose up --build
• Check Docker logs: docker-compose logs

License

MIT