first commit

2026-02-01 04:39:12 -05:00
commit bb35db384f
11 changed files with 819 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,149 @@
+# 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