# 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:
   ```bash
   cp /path/to/your/videos/*.mp4 ./videos/
   ```

2. **Start the application**:
   ```bash
   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:
```json
[
  {
    "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