150 lines
3.4 KiB
Markdown
150 lines
3.4 KiB
Markdown
# 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
|