An entry for the streamplace vod showcase
1# Streamhut
2
3Decentralized video streaming on AT Protocol, powered by serverless bundles.
4
5## Architecture
6
7```
8┌─────────────────────────────────────────────────────────────────────────────┐
9│ STREAMHUT │
10├─────────────────────────────────────────────────────────────────────────────┤
11│ │
12│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
13│ │ AppView │────▶│ Turso │ │ Frontend │ │
14│ │ Bundle │ │ (SQLite) │ │ (React) │ │
15│ └──────────────┘ └──────────────┘ └──────────────┘ │
16│ │ │ │
17│ │ indexes videos │ plays videos │
18│ ▼ ▼ │
19│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
20│ │ File Cache │◀───▶│ VOD Bundle │◀────│ at-run │ │
21│ │ /tmp/vod-cache │ (playback) │ │ Runner │ │
22│ └──────────────┘ └──────────────┘ └──────────────┘ │
23│ │ │
24│ ▼ │
25│ ┌──────────────┐ │
26│ │ stream.place │ │
27│ │ (HLS) │ │
28│ └──────────────┘ │
29│ │
30└─────────────────────────────────────────────────────────────────────────────┘
31```
32
33## Project Structure
34
35```
36├── apps/
37│ ├── backend/
38│ │ ├── api/ # VOD bundle - HLS proxying, thumbnails, sprites, sharing
39│ │ └── appview/ # Video indexer - crawls creators, stores in Turso (WIP)
40│ └── frontend/ # Nuxt 4 web app - video player UI
41│
42├── packages/at-run/
43│ ├── runtime/ # Bundle authoring SDK
44│ ├── cli/ # Deploy bundles to PDS
45│ ├── runner/ # Execute bundles in Deno sandbox
46│ └── lexicons/ # AT Protocol record schemas
47│
48└── DESIGN.md # Architecture decisions
49```
50
51## Quick Start
52
53```bash
54# Install dependencies
55bun install
56
57# Login to your AT Protocol PDS
58npm run login
59
60# Start the runner (dev mode with hot reload)
61npm run runner
62
63# In another terminal, start the frontend
64npm run web
65```
66
67## Common Tasks
68
69### Deploy Bundles
70
71```bash
72# Deploy both bundles
73npm run deploy:all
74
75# Deploy individually
76npm run deploy:vod
77npm run deploy:appview
78```
79
80### Development
81
82```bash
83# Start runner + frontend together
84npm run dev
85
86# Or separately:
87npm run runner # Start at-run runner
88npm run web # Start frontend dev server
89
90# Build bundles
91npm run bundle
92
93# Type check
94npm run typecheck
95```
96
97## Environment Variables
98
99Copy `.env.example` to `.env` and configure:
100
101```bash
102# Required for AppView
103TURSO_URL=libsql://your-db.turso.io
104TURSO_AUTH_TOKEN=your-token
105
106# Optional: Connect VOD to AppView
107APPVIEW_URL=https://at-run.example.com/bundle/.../streamhut-appview/latest
108
109# Frontend
110VITE_RUNNER_URL=https://at-run.example.com
111```
112
113## Bundles
114
115### VOD (`atmosphereconf-vod`)
116
117Serves video playback with thumbnails, preview sprites, and social sharing.
118
119| Endpoint | Description |
120|----------|-------------|
121| `GET /listVideos` | List videos (from AppView or fallback) |
122| `GET /getPlaylist` | HLS master playlist |
123| `GET /getThumbnail` | Video thumbnail |
124| `GET /getSprite` | Preview sprite sheet |
125| `GET /getVtt` | Sprite coordinates |
126| `GET /shareVideo` | Share page with OG meta tags |
127| `GET /shareCreator` | Creator share page with OG meta tags |
128
129**Job:** `syncAndProcessVideos` - runs every 10 minutes
130
131### AppView (`streamhut-appview`) *(Work in Progress)*
132
133Indexes `place.stream.video` records from registered AT Protocol creators.
134
135| Endpoint | Description |
136|----------|-------------|
137| `POST /init` | Initialize database schema |
138| `POST /registerCreator` | Add creator DID to index |
139| `POST /unregisterCreator` | Remove creator |
140| `GET /listVideos` | Query indexed videos |
141| `GET /getStats` | Get index statistics |
142| `POST /triggerSync` | Manual sync trigger |
143
144**Job:** `syncAllCreators` - runs every 15 minutes
145
146## Documentation
147
148### Applications
149- [VOD Bundle](./apps/backend/api/README.md) - Video playback API with HLS, thumbnails, and sharing
150- [Frontend](./apps/frontend/README.md) - Nuxt 4 web application
151- [AppView](./apps/backend/appview/README.md) - Video indexer *(work in progress)*
152
153### at-run Framework
154- [Overview](./packages/at-run/README.md) - Serverless execution on AT Protocol
155- [Runner](./packages/at-run/runner/README.md) - HTTP server for bundle execution
156- [Runtime](./packages/at-run/runtime/README.md) - Bundle authoring SDK *(docs coming soon)*
157- [CLI](./packages/at-run/cli/README.md) - Deployment tool *(docs coming soon)*
158
159### Other
160- [Design Decisions](./DESIGN.md) - Architecture decisions and rationale
161- [Hosting Guide](./packages/at-run/runner/HOSTING.md) - Deploy your own runner
162
163## Requirements
164
165- [Bun](https://bun.sh) v1.0+ - Runtime and bundler
166- [Deno](https://deno.land) v1.40+ - Sandbox execution
167- [Turso](https://turso.tech) account - Database (free tier works)
168
169## License
170
171MIT