source/DEPLOY.md

Deployment Guide for Hugging Face Spaces

Quick Deployment Steps

Option 1: Using Hugging Face Web Interface (Recommended)

1. Create a new Space:

   • Go to https://huggingface.co/new-space
   • Name: parakeet-progressive-streaming (or your preferred name)
   • License: mit
   • SDK: static
   • Click "Create Space"

2. Upload files:

   • Upload the entire dist/ folder contents to your Space
   • Upload README.md to the root (this will be displayed on the Space page)

   The file structure should look like:

   your-space/
   ├── README.md
   ├── index.html
   └── assets/
       ├── *.js
       ├── *.css
       └── *.wasm
   

3. Done! Your Space will be live at https://huggingface.co/spaces/YOUR_USERNAME/SPACE_NAME

Option 2: Using Git (Advanced)

1. Initialize git repository (if not already done):

   cd parakeet-web-demo
   git init
   git add dist/ README.md
   git commit -m "Initial commit: Parakeet progressive streaming demo"
   

2. Add Hugging Face remote:

   git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/SPACE_NAME
   

3. Push to Hugging Face:

   git push hf main
   

What Gets Deployed

The dist/ folder contains:

• index.html - Main HTML entry point
• assets/*.js - JavaScript bundles (React app, worker, libraries)
• assets/*.css - Stylesheets
• assets/*.wasm - ONNX Runtime WebAssembly files

Total size: ~47MB (mostly WASM files for ONNX Runtime)

Post-Deployment

After deployment, your Space will:

1. Load immediately (static site)
2. Download the Parakeet model (~2.5GB) on first use
3. Cache the model in the browser's IndexedDB for subsequent visits

Updating the Space

To update after making changes:

1. Rebuild:

   npm run build
   

2. Upload new dist/ contents via the web interface, or:

   git add dist/
   git commit -m "Update: description of changes"
   git push hf main
   

Testing Locally Before Deployment

npm run preview

This will serve the production build locally at http://localhost:4173

Troubleshooting

Space shows blank page

• Check browser console for errors
• Verify all files in dist/ were uploaded
• Ensure index.html is in the root directory

Model fails to load

• Check that the Space has WebGPU enabled (Chrome 113+, Edge 113+)
• Verify CORS headers are set correctly (Hugging Face handles this automatically)
• Check browser console for specific error messages

Performance is slow

• This is expected - see README.md for performance notes
• Ensure WebGPU is available (check console logs)
• Try on a different browser (Chrome/Edge recommended)

Browser Requirements

Recommend users use:

• Chrome 113+ or Edge 113+ for full WebGPU support
• Modern desktop/laptop (mobile may be very slow)
• Good internet connection for initial model download

Privacy & Security

The demo:

• ✅ Runs entirely client-side (no server processing)
• ✅ No data sent to any server
• ✅ Model cached locally in browser
• ✅ Microphone access required (browser prompt)