Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
141 lines (106 loc) · 4.16 KB

GETTING_STARTED.md

File metadata and controls

141 lines (106 loc) · 4.16 KB

Getting Started - Bitwig Sample Browser Extension

🎯 What This Extension Does

A native Linux sample browser that integrates directly into Bitwig Studio, providing access to royalty-free samples from Freesound.org and other sources without requiring Windows/Mac desktop applications.

🚀 Quick Start

1. Get Freesound API Key

  1. Visit https://freesound.org/apiv2/apply
  2. Register for a free API key
  3. Edit src/main/java/com/tcomer/bitwig/sampler/FreesoundClient.java
  4. Replace YOUR_FREESOUND_API_KEY with your actual key

2. Build Extension

./build.sh

3. Install in Bitwig

# Auto-install
gradle installExtension

# Or manual install  
cp build/extensions/SampleBrowser.bwextension ~/Bitwig\ Studio/Extensions/

4. Activate in Bitwig

  1. Open Bitwig Studio
  2. Go to Settings → Controllers
  3. Click Add
  4. Select Sample Browser by tcomer
  5. Extension panel appears in Bitwig interface

🎵 Usage

Search Samples

  • Text Search: Search by keywords (e.g., "kick drum", "ambient pad")
  • Genre Filter: Use genre-specific search actions
  • Results: View samples with metadata (duration, author, tags)

Preview & Import

  • Preview: Audition samples with project tempo sync
  • Download: Cache samples locally for offline access
  • Import: Drag samples directly to tracks or add to sample library

Sample Management

  • Local Cache: Downloaded samples stored in ~/.bitwig-sample-cache/
  • Offline Browse: Search previously downloaded samples
  • Smart Organization: Automatic tagging and metadata extraction

🛠️ Development Setup

Prerequisites

  • Java 11+ (compatible with Bitwig's JRE)
  • Gradle 7.0+ (or use included wrapper)
  • Bitwig Studio 4.2+
  • Internet connection for sample downloads

Development Workflow

# Build and test
./build.sh

# Install for testing
gradle installExtension  

# Restart Bitwig to load changes
# Test functionality in Bitwig Studio

# Check logs
tail -f ~/.BitwigStudio/log/BitwigStudio.log

🔧 Configuration

API Keys

Edit FreesoundClient.java to add your API credentials:

private static final String API_KEY = "your_actual_api_key_here";

Cache Location

Default: ~/.bitwig-sample-cache/ Modify in SampleCache.java constructor if needed.

Sample Quality

Configure download quality in FreesoundClient.java:

  • Original quality (recommended)
  • Preview quality (faster downloads)

🎯 Current Features (v1.0)

  • ✅ Freesound.org API integration
  • ✅ Sample search with filters
  • ✅ Local caching system
  • ✅ Basic Bitwig Studio integration
  • ✅ Preview functionality (foundation)
  • ✅ Import to tracks (foundation)

🚧 Planned Features (Future Versions)

  • 🔄 Advanced UI with rich sample browser
  • 🔄 Multiple sample source support (Looperman, etc.)
  • 🔄 Smart tempo/key matching
  • 🔄 AI-powered sample recommendations
  • 🔄 Advanced sample organization
  • 🔄 Splice/Loopcloud protocol reverse engineering

🐛 Troubleshooting

Extension Not Loading

  1. Check Bitwig Studio version (requires 4.2+)
  2. Verify extension file in ~/Bitwig Studio/Extensions/
  3. Check Bitwig logs for error messages
  4. Ensure proper Java compilation (run ./build.sh)

API Errors

  1. Verify Freesound API key is valid
  2. Check internet connection
  3. Review rate limits (2000 requests/day default)
  4. Check API service status

Sample Downloads Failing

  1. Verify write permissions to cache directory
  2. Check disk space availability
  3. Review network firewall settings
  4. Test with different sample sources

📚 Documentation

  • Full API Reference: docs/bitwig-extension-api.md
  • Architecture Overview: README.md (main project)
  • Component Documentation: Individual README.md files in each directory

🎵 Welcome to Linux-first sample library integration for Bitwig Studio!

This extension represents a paradigm shift from proprietary Windows/Mac desktop apps to open, API-driven sample library access that's designed for the Linux audio production workflow.