jknapp
d34d272cf0
Since pyproject.toml is configured to use PyTorch CUDA index by default, all builds automatically include CUDA support. Removed redundant separate CUDA build scripts and updated documentation. Changes: - Removed build-cuda.sh and build-cuda.bat (no longer needed) - Updated build.sh and build.bat to include CUDA by default - Added "uv sync" step to ensure CUDA PyTorch is installed - Updated messages to clarify CUDA support is included - Updated BUILD.md to reflect simplified build process - Removed separate CUDA build sections - Clarified all builds include CUDA support - Updated GPU support section - Updated CLAUDE.md with simplified build commands Benefits: - Simpler build process (one script per platform instead of two) - Less confusion about which script to use - All builds work on any system (GPU or CPU) - Automatic fallback to CPU if no GPU available - pyproject.toml is single source of truth for dependencies 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
226 lines
6.0 KiB
Markdown
226 lines
6.0 KiB
Markdown
# Building Local Transcription
|
|
|
|
This guide explains how to build standalone executables for Linux and Windows.
|
|
|
|
## Prerequisites
|
|
|
|
1. **Python 3.8+** installed on your system
|
|
2. **uv** package manager (install from https://docs.astral.sh/uv/)
|
|
3. All project dependencies installed (`uv sync`)
|
|
|
|
## Building for Linux
|
|
|
|
### Standard Build (includes CUDA support):
|
|
|
|
```bash
|
|
# Make the build script executable (first time only)
|
|
chmod +x build.sh
|
|
|
|
# Run the build script
|
|
./build.sh
|
|
```
|
|
|
|
This will:
|
|
- Install PyTorch with CUDA 12.1 support (configured in pyproject.toml)
|
|
- Bundle CUDA runtime libraries (~600MB extra)
|
|
- Create an executable that works on both GPU and CPU systems
|
|
- Automatically fall back to CPU if no CUDA GPU is available
|
|
|
|
The executable will be created in `dist/LocalTranscription/LocalTranscription`
|
|
|
|
### Manual build:
|
|
```bash
|
|
# Clean previous builds
|
|
rm -rf build dist
|
|
|
|
# Sync dependencies (includes CUDA PyTorch)
|
|
uv sync
|
|
|
|
# Remove incompatible enum34 package
|
|
uv pip uninstall -q enum34
|
|
|
|
# Build with PyInstaller
|
|
uv run pyinstaller local-transcription.spec
|
|
```
|
|
|
|
### Distribution:
|
|
```bash
|
|
cd dist
|
|
tar -czf LocalTranscription-Linux.tar.gz LocalTranscription/
|
|
```
|
|
|
|
## Building for Windows
|
|
|
|
### Standard Build (includes CUDA support):
|
|
|
|
```cmd
|
|
# Run the build script
|
|
build.bat
|
|
```
|
|
|
|
This will:
|
|
- Install PyTorch with CUDA 12.1 support (configured in pyproject.toml)
|
|
- Bundle CUDA runtime libraries (~600MB extra)
|
|
- Create an executable that works on both GPU and CPU systems
|
|
- Automatically fall back to CPU if no CUDA GPU is available
|
|
|
|
The executable will be created in `dist\LocalTranscription\LocalTranscription.exe`
|
|
|
|
### Manual build:
|
|
```cmd
|
|
# Clean previous builds
|
|
rmdir /s /q build
|
|
rmdir /s /q dist
|
|
|
|
# Sync dependencies (includes CUDA PyTorch)
|
|
uv sync
|
|
|
|
# Remove incompatible enum34 package
|
|
uv pip uninstall -q enum34
|
|
|
|
# Build with PyInstaller
|
|
uv run pyinstaller local-transcription.spec
|
|
```
|
|
|
|
### Distribution:
|
|
- Compress the `dist\LocalTranscription` folder to a ZIP file
|
|
- Or use an installer creator like NSIS or Inno Setup
|
|
|
|
## Important Notes
|
|
|
|
### Cross-Platform Building
|
|
|
|
**You cannot cross-compile!**
|
|
- Linux executables must be built on Linux
|
|
- Windows executables must be built on Windows
|
|
- Mac executables must be built on macOS
|
|
|
|
### First Run
|
|
|
|
On the first run, the application will:
|
|
1. Create a config directory at `~/.local-transcription/` (Linux) or `%USERPROFILE%\.local-transcription\` (Windows)
|
|
2. Download the Whisper model (if not already present)
|
|
3. The model will be cached in `~/.cache/huggingface/` by default
|
|
|
|
### Executable Size
|
|
|
|
The built executable will be large (300MB - 2GB+) because it includes:
|
|
- Python runtime
|
|
- PySide6 (Qt framework)
|
|
- PyTorch/faster-whisper
|
|
- NumPy, SciPy, and other dependencies
|
|
|
|
### Console Window
|
|
|
|
By default, the console window is visible (for debugging). To hide it:
|
|
|
|
1. Edit `local-transcription.spec`
|
|
2. Change `console=True` to `console=False` in the `EXE` section
|
|
3. Rebuild
|
|
|
|
### GPU Support
|
|
|
|
**CUDA support is included by default** in all builds via the PyTorch CUDA configuration in `pyproject.toml`.
|
|
|
|
**Yes, you CAN build with CUDA support on systems without NVIDIA GPUs!**
|
|
|
|
PyTorch provides CUDA-enabled builds that bundle the CUDA runtime libraries. This means:
|
|
|
|
1. **You don't need NVIDIA hardware** to create CUDA-enabled builds
|
|
2. **The executable will work everywhere** - on systems with or without NVIDIA GPUs
|
|
3. **Automatic fallback** - the app detects available hardware and uses GPU if available, CPU otherwise
|
|
4. **Larger file size** - adds ~600MB-1GB to the executable size
|
|
|
|
**When users run the executable:**
|
|
- If they have an NVIDIA GPU with drivers: Uses GPU acceleration
|
|
- If they don't have NVIDIA GPU: Automatically uses CPU
|
|
- No configuration needed - it just works!
|
|
|
|
#### AMD GPU Support
|
|
|
|
- **ROCm**: Requires special PyTorch builds from AMD
|
|
- Not recommended for general distribution
|
|
- The default CUDA build already works on all systems (NVIDIA GPU, AMD GPU, or CPU-only)
|
|
|
|
### Optimizations
|
|
|
|
To reduce size:
|
|
|
|
1. **Remove unused model sizes**: The app downloads models on-demand, so you don't need to bundle them
|
|
2. **Use UPX compression**: Already enabled in the spec file
|
|
3. **Exclude dev dependencies**: Only build dependencies are needed
|
|
|
|
## Testing the Build
|
|
|
|
After building, test the executable:
|
|
|
|
### Linux:
|
|
```bash
|
|
cd dist/LocalTranscription
|
|
./LocalTranscription
|
|
```
|
|
|
|
### Windows:
|
|
```cmd
|
|
cd dist\LocalTranscription
|
|
LocalTranscription.exe
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Missing modules error
|
|
If you get "No module named X" errors, add the module to the `hiddenimports` list in `local-transcription.spec`
|
|
|
|
### DLL errors (Windows)
|
|
Make sure Visual C++ Redistributable is installed on the target system:
|
|
https://aka.ms/vs/17/release/vc_redist.x64.exe
|
|
|
|
### Audio device errors
|
|
The application needs access to audio devices. Ensure:
|
|
- Microphone permissions are granted
|
|
- Audio drivers are installed
|
|
- PulseAudio (Linux) or Windows Audio is running
|
|
|
|
### Model download fails
|
|
Ensure internet connection on first run. Models are downloaded from:
|
|
https://huggingface.co/guillaumekln/faster-whisper-base
|
|
|
|
## Advanced: Adding an Icon
|
|
|
|
1. Create or obtain an `.ico` file (Windows) or `.png` file (Linux)
|
|
2. Edit `local-transcription.spec`
|
|
3. Change `icon=None` to `icon='path/to/your/icon.ico'`
|
|
4. Rebuild
|
|
|
|
## Advanced: Creating an Installer
|
|
|
|
### Windows (using Inno Setup):
|
|
|
|
1. Install Inno Setup: https://jrsoftware.org/isinfo.php
|
|
2. Create an `.iss` script file
|
|
3. Build the installer
|
|
|
|
### Linux (using AppImage):
|
|
|
|
```bash
|
|
# Install appimagetool
|
|
wget https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage
|
|
chmod +x appimagetool-x86_64.AppImage
|
|
|
|
# Create AppDir structure
|
|
mkdir -p LocalTranscription.AppDir/usr/bin
|
|
cp -r dist/LocalTranscription/* LocalTranscription.AppDir/usr/bin/
|
|
|
|
# Create desktop file and icon
|
|
# (Create .desktop file and icon as needed)
|
|
|
|
# Build AppImage
|
|
./appimagetool-x86_64.AppImage LocalTranscription.AppDir
|
|
```
|
|
|
|
## Support
|
|
|
|
For build issues, check:
|
|
1. PyInstaller documentation: https://pyinstaller.org/
|
|
2. Project issues: https://github.com/anthropics/claude-code/issues
|