Initial commit

README.md

@@ -0,0 +1,193 @@
+# auto-transcoder
+
+**Auto-transcoder** is a Python-based media transcoding application that automatically processes media files when they are added to a specified directory. It leverages Redis for tracking media state and Celery for handling transcoding tasks asynchronously. The application is containerised using Docker for easy deployment and management.
+
+---
+
+## 📦 Features
+
+- **Automatic Transcoding**: Detects new media files in a watched directory and triggers transcoding tasks.
+- **Redis Integration**: Tracks media state (e.g., whether a file has been transcoded) using Redis.
+- **Celery Worker Support**: Uses Celery to handle transcoding tasks in the background.
+- **Docker-Ready**: Comes with Dockerfiles for both the server and worker components.
+- **Cross-Platform Compatibility**: Runs on Linux (ARM64 and AMD64 architectures).
+
+---
+
+## 📦 Requirements
+
+- **Redis Server**: Required for media state tracking.
+- **Celery Worker**: Needed to process transcoding tasks.
+- **Docker**: For containerisation and deployment.
+
+---
+
+## 📁 Project Structure
+
+Here are a few key files in the project structure:
+
+```
+auto-transcoder/
+├── server.Dockerfile
+├── worker.Dockerfile
+├── pyproject.toml
+├── src/
+│   └── auto_transcoder/
+│       ├── model.py
+│       ├── tasks.py
+│       └── server.py
+```
+
+---
+
+## 🚀 Getting Started
+
+### 1. **Build Docker Images**
+
+Run the following commands to build the server and worker Docker images:
+
+```bash
+docker build -t auto-transcoder-server -f server.Dockerfile .
+docker build -t auto-transcoder-worker -f worker.Dockerfile .
+```
+
+### 2. **Run Redis Server**
+
+Ensure a Redis server is running. You can use Docker:
+
+```bash
+docker run --name redis -d -p 6379:6379 redis
+```
+
+### 3. **Run the Server and Worker**
+
+To run the server and worker, use Docker Compose or individual commands. Here’s an example using Docker Compose:
+
+```yaml
+# docker-compose.yml
+services:
+  redis:
+    image: redis
+    ports:
+      - "6379:6379"
+  server:
+    image: auto-transcoder-server
+    command:
+      - /data
+      - --recycle-bin
+      - /data/recycle_bin
+    ports:
+      - "5000:5000"
+    volumes:
+      - /path/to/media:/data
+    depends_on:
+      - redis
+    environment:
+      - REDIS_URL=redis://redis:6379
+  worker:
+    image: auto-transcoder-worker
+    volumes:
+      - /path/to/media:/data
+    depends_on:
+      - redis
+    environment:
+      - REDIS_URL=redis://redis:6379
+```
+
+Start services with:
+
+```bash
+docker compose up -d
+```
+
+> 🔍 Note: Replace `/path/to/media` with the actual path to the directory you want to watch.
+
+You may find a standalone docker-compose.yml example if you need help getting started [here](docker-compose.example.yml).
+
+---
+
+## 📌 Configuration
+
+### Command Line Arguments
+
+- `directory_to_watch`: Path to the directory where media files are stored. This is a required argument.
+- `--recycle-bin`: Path to a directory where original media files will be moved after transcoding. If not provided, the original files will be deleted.
+
+### Environment Variables
+
+- `REDIS_URL`: URL to your Redis instance (e.g., `redis://redis:6379`).
+
+---
+
+## 🧪 Usage
+
+1. Place media files in the watched directory.
+2. The server will automatically detect new files and add them to the queue.
+3. A Celery worker will process the transcoding tasks in the background.
+
+
+---
+
+## 📦 Dependencies
+
+This project uses the following dependencies (managed via Poetry):
+
+- `celery[redis]`
+- `flask`
+- `python-magic`
+- `redis`
+- `asyncio`
+
+Install them with:
+
+```bash
+poetry install
+```
+
+---
+
+## 🧱 Development
+
+To set up the development environment:
+
+1. Install [Poetry](https://python-poetry.org/docs/).
+2. Run `poetry install` to install dependencies.
+3. Run the server with `poetry run python src/auto_transcoder/server.py` (ensure Redis is running).
+4. Run the worker with `poetry run celery -A auto_transcoder.tasks worker --loglevel=info`.
+
+---
+
+## 📝 Notes
+
+- Ensure that both the worker and server instances have access to the media files at the same path.
+  - If you're using Docker, this can be achieved by mounting the media directory as a volume in your Docker Compose setup.
+- The `pyproject.toml` defines package structure and build settings. It currently uses `poetry-core` for building the package.
+- The `MediaDTO` class encapsulates media file metadata, and the `RedisManager` class is used to manage Redis connections.
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License**. See the [LICENCE](LICENCE) file for details.
+
+---
+
+## 📈 Contributing
+
+Contributions are welcome! To contribute:
+
+1. Fork the repository.
+2. Create a feature branch.
+3. Make your changes.
+4. Submit a pull request.
+
+This repository uses British English spelling. Please ensure that your contributions adhere to this standard.
+
+---
+
+## 📚 References
+
+- [Poetry Documentation](https://python-poetry.org/docs/)
+- [Docker Documentation](https://docs.docker.com/)
+- [Redis Documentation](https://redis.io/docs/)
+- [Celery Documentation](https://docs.celeryproject.org/)