{"id":50772421,"url":"https://github.com/jo56/pedalboard-audio-studio","last_synced_at":"2026-06-11T20:03:13.832Z","repository":{"id":319088481,"uuid":"1076569855","full_name":"jo56/pedalboard-audio-studio","owner":"jo56","description":"Manipulate audio using Spotify's Pedalboard library","archived":false,"fork":false,"pushed_at":"2026-05-30T20:48:24.000Z","size":714,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T22:19:38.100Z","etag":null,"topics":["audio","audio-processing","audio-production","augmentation","guitar","music","pedalboard","python","spotify","typescript"],"latest_commit_sha":null,"homepage":"https://pedalboard-audio-studio.pages.dev/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jo56.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-15T03:45:51.000Z","updated_at":"2026-05-30T20:48:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"64d902a2-1211-4b1f-9bb3-77cd2751ad2c","html_url":"https://github.com/jo56/pedalboard-audio-studio","commit_stats":null,"previous_names":["jo56/pedalboard-audio-studio"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/jo56/pedalboard-audio-studio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jo56%2Fpedalboard-audio-studio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jo56%2Fpedalboard-audio-studio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jo56%2Fpedalboard-audio-studio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jo56%2Fpedalboard-audio-studio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jo56","download_url":"https://codeload.github.com/jo56/pedalboard-audio-studio/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jo56%2Fpedalboard-audio-studio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34215282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","audio-processing","audio-production","augmentation","guitar","music","pedalboard","python","spotify","typescript"],"created_at":"2026-06-11T20:03:13.195Z","updated_at":"2026-06-11T20:03:13.821Z","avatar_url":"https://github.com/jo56.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pedalboard Audio Studio\n\n  \u003cdiv align=\"center\"\u003e\n      \u003ca href=\"https://pedalboard-audio-studio.pages.dev\" target=\"_blank\"\u003e\n          \u003cimg src=\"assets/pedalboard-studio-1.png\" alt=\"pedalboard preview\"\u003e\n      \u003c/a\u003e\n      \u003cbr\u003e\n      \u003ca href=\"https://pedalboard-audio-studio.pages.dev\" target=\"_blank\"\u003e\n          \u003cb\u003ehttps://pedalboard-audio-studio.pages.dev\u003c/b\u003e\n      \u003c/a\u003e\n  \u003c/div\u003e\n\n\u003cbr\u003e\n\nA fullstack web application that provides a UI for manipulating audio files using [Spotify's Pedalboard](https://github.com/spotify/pedalboard) library. Upload audio files, design complex pedal chains, host VST3 plugins, and save reusable presets.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n## Features\n\n- **Drag \u0026 Drop File Upload** - MP3, WAV, FLAC, OGG, and M4A support\n- **Visual Waveform Display** - Real-time waveform visualization with playback controls\n- **Comprehensive Pedalboard Coverage** - 24 native effects including dynamics, filters, modulation, convolution IRs, GSM codec emulation, and more\n- **External VST3 Hosting** - Drop compatible plugins in `backend/plugins` and use them in any chain\n- **Effect Chain Builder** - Add, remove, and reorder effects with ease\n- **Typed Parameter Controls** - Sliders, toggles, selects, and text inputs adjust parameters with live feedback\n- **Preset Management** - Save, list, download, and reuse effect chains through the API\n- **Download Processed Audio** - Export processed audio with a single click\n\n## Tech Stack\n\n### Backend\n- **Python 3.11+**\n- **FastAPI**\n- **uv**\n- **Pedalboard 0.9.8** - Spotify's audio effects library\n- **Uvicorn** - ASGI server\n- **slowapi** - Rate limiting middleware\n- **python-magic** - File type validation\n- **aiofiles** - Async file operations\n\n\n### Frontend\n- **React 19** with **TypeScript**\n- **Vite 7** build tooling\n- **Tailwind CSS 4** styling\n- **WaveSurfer.js** for waveform rendering\n- **Axios** HTTP client\n- **React Dropzone** for file uploads\n\n## Project Structure\n\n```\npedalboard-test/\n|-- backend/\n|   |-- main.py             # FastAPI server\n|   |-- effects.py          # Effect registry and processing\n|   |-- presets.py          # Preset persistence helpers\n|   |-- security.py         # Security utilities and session management\n|   |-- pyproject.toml      # Python dependencies managed by uv\n|   |-- .env.example        # Environment variables template\n|   |-- uploads/            # Uploaded audio (runtime)\n|   |-- processed/          # Processed audio (runtime)\n|   |-- presets/            # Saved effect presets (runtime)\n|   |-- impulses/           # Impulse responses for convolution effects\n|   `-- plugins/            # Optional VST3 binaries\n|-- frontend/\n|   |-- public/\n|   |-- src/\n|   |   |-- components/\n|   |   |-- utils/\n|   |   |-- api.ts\n|   |   |-- theme.ts\n|   |   |-- types.ts\n|   |   `-- App.tsx\n|   |-- .env.example        # Environment variables template\n|   |-- package.json\n|   `-- vite.config.ts\n|-- railway.json            # Railway deployment configuration\n|-- scripts/                # Deployment and utility scripts\n`-- README.md\n```\n\n## Setup Instructions\n\n### Prerequisites\n\n- Python 3.11 or higher\n- [uv](https://github.com/astral-sh/uv) (for Python environment and dependency management)\n- Node.js 16 or higher\n- npm (or yarn/pnpm)\n\n### Backend Setup\n\n```bash\ncd backend\nuv python install 3.11\nuv sync\nuv run uvicorn main:app --reload\n```\n\nThe backend will be available at `http://localhost:8000`.\n\nCreate a `.env` file (see `backend/.env.example`) to configure:\n- `CORS_ALLOWED_ORIGINS` - Production origins for CORS (e.g., your Cloudflare Pages URL)\n- `LOCAL_DEPLOYMENT` - Set to `true` in development to disable rate limiting\n\n### Frontend Setup\n\n```bash\ncd frontend\nnpm install\nnpm run dev\n```\n\nThe frontend will be available at `http://localhost:5173`.\nDuplicate `frontend/.env.example` to `.env` (or `.env.production`) and point `VITE_API_URL` at the deployed backend when building for Cloudflare Pages.\n\n## Usage\n\n1. **Upload Audio** - Drag and drop an audio file or click to browse\n2. **Add Effects** - Choose effects from the dropdown and click \"Add\"\n3. **Adjust Parameters** - Use sliders, inputs, or selectors per parameter type\n4. **Reorder Effects** - Drag any effect header to reposition the chain order\n5. **Process Audio** - Click \"Process Audio\" to render the effect chain\n6. **Compare \u0026 Download** - Audition original vs processed audio and export\n7. **Save Presets (API)** - POST to `/presets` with the current chain to reuse later\n\n### Working with Impulse Responses \u0026 VST3 Plugins\n\n- Place impulse responses (WAV/AIFF) in `backend/impulses`. They will appear as options for the Convolution effect.\n- Place platform-specific `.vst3` bundles inside `backend/plugins` (or provide absolute paths) to host third-party effects.\n\n## Available Effects\n\n| Effect | Description | Key Parameters |\n|--------|-------------|----------------|\n| Reverb | Adds spatial ambience | room_size, damping, wet_level |\n| Delay | Creates echoes | delay_seconds, feedback, mix |\n| Compressor | Controls dynamic range | threshold_db, ratio, attack_ms, release_ms |\n| Limiter | Prevents peaks | threshold_db, release_ms |\n| Gain | Adjusts level | gain_db |\n| Distortion | Harmonic saturation | drive_db |\n| Chorus | Modulated thickening | rate_hz, depth, mix |\n| Phaser | Sweeping phase cancellations | rate_hz, depth, centre_frequency_hz |\n| Bitcrush | Lo-fi bit reduction | bit_depth |\n| Highpass | Removes lows | cutoff_frequency_hz |\n| Lowpass | Removes highs | cutoff_frequency_hz |\n| Ladder Filter | Moog-style filter | mode, cutoff_hz, resonance, drive |\n| High/Low Shelf | Tone shaping | cutoff_frequency_hz, gain_db, q |\n| Peak Filter | EQ boost/cut | cutoff_frequency_hz, gain_db, q |\n| Pitch Shift | Alters pitch | semitones |\n| Clipping | Hard clipping | threshold_db |\n| MP3 Compressor | Codec artifacts | vbr_quality |\n| Resample | Aliasing via resampling | target_sample_rate, quality |\n| Noise Gate | Suppresses noise | threshold_db, ratio, attack_ms, release_ms |\n| GSM Full Rate | 2G cellular compression | quality |\n| Convolution | IR-based filtering | impulse_response, mix |\n| Invert | Flips polarity | - |\n| VST3 Plugin | Host external plugin | plugin_path, plugin_name, initialization_timeout, parameter_values |\n\n## Preset API\n\nEffect presets are stored as JSON in `backend/presets`. Endpoints:\n\n- `GET /presets` - List stored presets\n- `POST /presets` - Create a preset from an effect chain\n- `GET /presets/{preset_id}` - Retrieve full preset payload\n- `GET /presets/{preset_id}/download` - Download preset JSON\n- `DELETE /presets/{preset_id}` - Remove a preset\n- `POST /process` - Accepts either an `effects` array or a `preset_id`\n\nExample preset creation payload:\n\n```json\n{\n  \"name\": \"Bright Guitar\",\n  \"description\": \"Sparkly chorus and delay\",\n  \"effects\": [\n    { \"type\": \"chorus\", \"params\": { \"depth\": 0.35, \"mix\": 0.5 } },\n    { \"type\": \"delay\", \"params\": { \"delay_seconds\": 0.42, \"feedback\": 0.3, \"mix\": 0.4 } }\n  ]\n}\n```\n\n## API Endpoints\n\n- `GET /` - Health check\n- `GET /effects` - Available effects with metadata and parameter types\n- `GET /presets` - List presets\n- `POST /presets` - Save effect preset\n- `GET /presets/{preset_id}` - Fetch preset details\n- `GET /presets/{preset_id}/download` - Download preset JSON\n- `DELETE /presets/{preset_id}` - Delete preset\n- `POST /upload` - Upload audio file\n- `POST /process` - Process audio with inline `effects` or `preset_id`\n- `GET /download/{file_id}` - Download processed audio\n- `DELETE /cleanup/{file_id}` - Remove uploaded/processed files\n\n## Deployment\n\n### Recommended: Railway backend + Cloudflare Pages frontend\n\nThe project includes `railway.json` configured for automatic Railway deployments using Nixpacks.\n\n1. Push this repository to GitHub so both platforms can access it.\n2. **Railway (backend)**\n   - Create a new service and connect your GitHub repository.\n   - Railway will automatically detect `railway.json` and use Nixpacks builder.\n   - Set the root directory to `backend/` in Railway settings.\n   - Add environment variables:\n     - `CORS_ALLOWED_ORIGINS` - Your Cloudflare Pages domain (comma separated for multiple origins)\n     - `LOCAL_DEPLOYMENT=false` - Enable rate limiting in production\n   - Attach a volume if you need processed audio or presets to persist across deployments.\n3. **Cloudflare Pages (frontend)**\n   - Create a Pages project from the same repo and set the root directory to `frontend`.\n   - Use `npm run build` as the build command and `dist` as the output directory.\n   - Define `VITE_API_URL` (for both Preview and Production environments) with the public Railway URL from step 2.\n4. Rebuild both services. The frontend will talk to the backend via the configured API URL with CORS automatically satisfied.\n\n## Development Notes\n\n- Swagger UI: http://localhost:8000/docs\n- ReDoc: http://localhost:8000/redoc\n- Frontend uses Vite HMR for instant feedback\n\n### Testing / Validation\n\n- Frontend lint: `npm run lint`\n- Frontend production build: `npm run build`\n- Backend syntax check (from `backend/`): `uv run python -m compileall main.py effects.py presets.py`\n\n## Future Enhancements\n\n- [ ] UI for managing presets from the web app\n- [ ] Real-time audio preview while editing parameters\n- [ ] Batch processing for multiple files\n- [ ] Expanded plugin metadata introspection for VST3 hosts\n- [ ] Export to multiple audio formats\n- [ ] Optional user authentication and cloud storage\n\n## Security Features\n\n- **Rate Limiting** - API endpoints are rate-limited using slowapi (configurable via `LOCAL_DEPLOYMENT` environment variable)\n- **User Session Management** - Per-user file quotas and processing limits to prevent abuse\n- **File Validation** - Uploaded audio files are validated for content type and size\n- **Session Cleanup** - Automatic cleanup of files older than 24 hours\n- **CORS Protection** - Configurable CORS origins for frontend access\n- No API keys or credentials are stored in this repo; set secrets via deployment platforms or local environment variables\n- Runtime directories (`backend/uploads`, `backend/processed`, `backend/presets`, `backend/plugins`, `backend/impulses`) are git ignored\n\n## License\n\nMIT License - Copyright (c) 2025 John O'Farrell\n\nThis project uses Spotify's Pedalboard library. Refer to the [Pedalboard license](https://github.com/spotify/pedalboard/blob/master/LICENSE) for details on that dependency.\n\n## Acknowledgments\n\n- [Spotify Pedalboard](https://github.com/spotify/pedalboard) - core DSP engine\n- Thanks to the FastAPI and React communities for great tooling\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjo56%2Fpedalboard-audio-studio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjo56%2Fpedalboard-audio-studio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjo56%2Fpedalboard-audio-studio/lists"}