README.md

---
title: Odyssey Backend
emoji: 🎥
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: 5.38.2
app_file: app.py
pinned: false
short_description: Video upload backend for Odyssey adventure game
---

# 🎥 Odyssey Backend

Backend service for the [Odyssey](https://huggingface.co/spaces/Fraser/odyssey) interactive video adventure game.

## Features

- **Video Upload**: Upload generated adventure videos to HuggingFace dataset
- **UUID Generation**: Each video gets a unique identifier
- **Public URLs**: Serve videos via HuggingFace CDN
- **Gradio API**: Simple API for programmatic access

## Architecture

- **Frontend**: [odyssey](https://huggingface.co/spaces/Fraser/odyssey) - Interactive game interface
- **Backend**: This Space - Video upload service
- **Storage**: [odyssey-videos](https://huggingface.co/datasets/Fraser/odyssey-videos) - Dataset of generated videos

## API Usage

### JavaScript/TypeScript

```javascript
import { Client } from "@gradio/client";

const client = await Client.connect("Fraser/odyssey-backend");

// Upload video
const result = await client.predict("/upload_video", {
    video_file: blob // or file handle
});

// Parse result
const data = JSON.parse(result.data[0]);
console.log(data.uuid, data.url, data.share);
```

### Python

```python
from gradio_client import Client

client = Client("Fraser/odyssey-backend")

# Upload video
result = client.predict("/upload_video", video_file="path/to/video.mp4")
```

## Deployment

### Environment Variables

Set these in Space Settings → Repository secrets:

- `HF_TOKEN`: HuggingFace token with write permissions to `Fraser/odyssey-videos` dataset

### Local Development

```bash
pip install -r requirements.txt
export HF_TOKEN=your_token_here
python app.py
# Server runs at http://localhost:7860
```

## Dataset Structure

All videos are stored in `Fraser/odyssey-videos`:

```
{uuid}.mp4
{uuid}.mp4
...
```

Each video can be accessed via:
- Direct URL: `https://huggingface.co/datasets/Fraser/odyssey-videos/resolve/main/{uuid}.mp4`
- Frontend URL: `https://fraser-odyssey.static.hf.space/?id={uuid}`

## Tech Stack

- **Gradio**: API framework and web interface
- **HuggingFace Hub**: Dataset storage backend
- **Python**: Core server logic