This is a submission for the DEV's Worldwide Show and Tell Challenge Presented by Mux
What I Built
README2Video is a web application that automatically transforms GitHub README files into professional promotional videos.
README.md → AI Analysis → Video Generation → Mux Streaming → Share!
Paste a GitHub URL, choose your style, and get a cinematic promo video in minutes. No editing skills required.
My Pitch Video
Meta twist: This pitch video was generated by README2Video itself, from its own README. The app pitched itself. 🎬
Video Preview (Powered by Mux)
Here's an animated preview generated automatically by Mux:
Demo
- Live App: readme-to-video.onrender.com
- GitHub Repo: github.com/fracabu/readme-to-video
How to Test (2 minutes setup, all free!)
The app uses BYOK (Bring Your Own Keys) - this keeps costs transparent and gives you full control.
| Service | How to Get Key | Cost |
|---|---|---|
| Mux | mux.com - Create free account | Free (no credit card) |
| OpenRouter | openrouter.ai - Sign up, get API key | Free models available! |
| Kie.ai | kie.ai - Sign up, get API key | Free credits on signup |
Free models tip: In OpenRouter, select models ending with :free like deepseek/deepseek-r1:free or google/gemini-2.0-flash-exp:free.
The Story Behind It
Every developer knows this pain: you build something amazing, but creating a promo video takes hours (or days), costs money, and requires skills you don't have.
I wanted to solve this for myself and every developer out there.
The solution? Let AI do the heavy lifting:
- Analyze the README to understand what the project does
- Generate a compelling script with scenes
- Create stunning visuals with Sora 2
- Host on Mux for instant streaming
Now any developer can go from README to promo video in under 5 minutes.
The Opportunity
There are 300+ million repositories on GitHub. Every single one could benefit from a promo video.
- Indie developers launching products
- Open source projects seeking contributors
- Startups pitching to investors
- Students showcasing portfolios
README2Video turns a $500+ video production into a $2 automated process. That's the kind of democratization that scales.
Technical Highlights
Architecture
| Layer | Technology |
|---|---|
| Frontend | Next.js 14, React 18, Tailwind CSS, shadcn/ui |
| LLM | Multi-provider: Claude, GPT-4, Gemini, OpenRouter (free tier!) |
| Video AI | Kie.ai Sora 2 - cinematic text-to-video |
| Streaming | Mux Video API |
| Real-time | Server-Sent Events for live progress |
Key Features
- Multi-Provider LLM: Choose between Anthropic, OpenAI, Google, or free models via OpenRouter
- Video Styles: Tech, Minimal, or Energetic aesthetics
- Durations: 15s, 30s, or 60s videos
- Real-time Progress: SSE updates showing each generation step
- BYOK Model: Users bring their own API keys - no hidden costs, full transparency
- Dynamic Thumbnail Slider: Interactive time picker (0-15s) to select the perfect thumbnail
- Animated GIF Preview: One-click GIF generation for social sharing
- MP4 Download: Direct download button for offline use
Use of Mux (Additional Prize Category)
README2Video leverages 6 distinct Mux features - all exposed in the UI for users to interact with:
1. Programmatic Upload API
Videos generated by Sora 2 are uploaded directly to Mux via the Node SDK:
import Mux from '@mux/mux-node';
const mux = new Mux({
tokenId: process.env.MUX_TOKEN_ID,
tokenSecret: process.env.MUX_TOKEN_SECRET,
});
// Upload generated video to Mux
const asset = await mux.video.assets.create({
input: [{ url: generatedVideoUrl }],
playback_policy: ['public'],
encoding_tier: 'baseline'
});
2. Adaptive Bitrate Streaming
Mux automatically transcodes every video into multiple resolutions and bitrates. Users get smooth playback regardless of their connection:
// Mux handles all transcoding automatically
// Users stream at optimal quality for their bandwidth
const streamUrl = `https://stream.mux.com/${playbackId}.m3u8`;
3. Playback URL Generation + MP4 Download
Each video gets a unique, shareable streaming URL - plus a direct download option:
// Get the playback ID from the asset
const playbackId = asset.playback_ids[0].id;
// Generate streaming URL (HLS format)
const streamUrl = `https://stream.mux.com/${playbackId}.m3u8`;
// Generate direct MP4 for download
const mp4Url = `https://stream.mux.com/${playbackId}/medium.mp4`;
In the app: A prominent "Download MP4" button lets users save their video locally for offline use or uploading to other platforms.
4. Dynamic Thumbnails with Interactive Slider
Mux generates thumbnails at any timestamp. We built an interactive slider so users can scrub through their video and pick the perfect frame:
// Thumbnail at specific time (in seconds)
const thumbnail = `https://image.mux.com/${playbackId}/thumbnail.png?time=5`;
// Custom dimensions
const customThumb = `https://image.mux.com/${playbackId}/thumbnail.png?time=10&width=1280&height=720`;
In the app: Users drag a slider (0-15s) and see the thumbnail update in real-time. One click copies the URL for social sharing.
Example - Dynamic thumbnail from our pitch video:
5. Animated GIF Previews
Generate eye-catching GIF previews for social media and documentation:
// Animated GIF from any segment
const gifPreview = `https://image.mux.com/${playbackId}/animated.gif?start=0&end=10&width=480`;
// Customize FPS for smaller file size
const optimizedGif = `https://image.mux.com/${playbackId}/animated.gif?start=2&end=8&fps=15&width=320`;
In the app: GIF previews are lazy-loaded (click to view) to save bandwidth. Users can copy the GIF URL instantly for sharing on Twitter, Discord, or README files.
Example - Animated preview of our pitch video:
6. Embeddable Player
Users get one-click access to embed code for any platform:
<!-- Mux Player embed -->
<iframe
src="https://player.mux.com/{playbackId}"
width="640"
height="360"
frameborder="0"
allowfullscreen>
</iframe>
<!-- Or use the stream URL directly -->
<video controls>
<source src="https://stream.mux.com/{playbackId}.m3u8" type="application/x-mpegURL">
</video>
Why Mux Was the Right Choice
| Requirement | Mux Solution |
|---|---|
| Fast integration | Clean SDK, 10 lines of code to upload |
| No infrastructure | Mux handles encoding, CDN, player |
| Auto-optimization | Adaptive streaming out of the box |
| Rich media features | Thumbnails, GIFs, storyboards - all automatic |
| Developer experience | Excellent docs, predictable API |
| Fair pricing | Pay only for what you use |
Building README2Video with Mux took minutes instead of days. That's exactly the developer experience I wanted to pass on to my users.
Challenges I Faced
1. Video Concatenation
Generating multi-scene videos (30s, 60s) required stitching multiple Sora 2 clips. Solution: FFmpeg with crossfade transitions on the server.
2. Long Generation Times
60-second videos (4 scenes) can take 5+ minutes. Solution: Server-Sent Events for real-time progress updates so users know exactly what's happening.
3. Free Tier Hosting Timeouts
Serverless platforms timeout during long generations. Solution: Deployed on Render as a persistent Node.js process.
What's Next
- [x]
Dynamic Thumbnail Slider- Done! Interactive time picker in result view - [x]
Animated GIF Preview- Done! Lazy-loaded GIF for social sharing - [x]
MP4 Download- Done! One-click download button - [ ] Mux Player React component for enhanced playback controls
- [ ] Auto-generated captions using Mux's transcription API
- [ ] Storyboard preview before final generation
- [ ] Webhook notifications when video is ready
- [ ] Batch processing for multiple READMEs
Built with ❤️ and AI | Powered by Mux, OpenRouter, Kie.ai & Sora 2
By submitting this project, I confirm that my video adheres to Mux's terms of service: https://www.mux.com/terms
Top comments (0)