Building a Distributable
How to package the application into a standalone executable for users without Python installed.
If you want to share your version of the Roblox Audio Bulk Uploader with other users who do not have Python installed, you will need to package the application into a standalone executable.
There are two primary tools you can use to achieve this: PyInstaller and Nuitka.
1. Option A: PyInstaller
PyInstaller bundles the Python interpreter and all dependencies into a single executable or directory.
To build with PyInstaller, use the provided specification file:
cd src
pyinstaller main.specLocation Note: Ensure you run the PyInstaller command from inside the src/ directory, as that is where main.spec is located, not the repository root.
2. Option B: Nuitka
Nuitka is an alternative that translates your Python code into C++ and compiles it into native machine code.
Why use Nuitka? It offers stronger protection against casual reverse-engineering of your custom mixing and upload logic compared to PyInstaller (which merely bundles Python bytecode).
To build with Nuitka, refer to the BUILD_NOTES.md file (if present in your repository) for the full build script and necessary compiler flags.
3. The keyring and pedalboard Caveat
Whether you choose PyInstaller or Nuitka, there is a known complication when bundling the keyring and pedalboard libraries.
Both of these libraries rely on native binaries or specific OS-level backends. Bundling tools often miss these implicit dependencies during the build process.
Crucially, this failure will not happen on your development machine. Because you have Python installed globally, the bundled app might silently fall back to your system's Python environment and work perfectly. The error will only surface on a machine that does not have Python installed.
Always Test on a Clean VM: Before distributing your build to users, you must test the executable on a clean Virtual Machine (or sandbox) that has absolutely no Python installation. This is the only way to verify that all dependencies were bundled correctly.
4. Verification Checklist
When testing your build on the clean VM, run through this specific checklist to verify that the bundling gaps did not affect your app:
- GUI Renders Correctly: The application opens without instantly crashing.
- API Key Persistence: Enter an API key, close the app, and restart it. The key should be remembered (verifies
keyringbackend is bundled). - Mix Audio Works: Run a file through the "Mix Audio" feature and confirm output files are generated (verifies core DSP logic).
- Preview Play Works: Click the Preview Play button in the queue and ensure audio actually plays (verifies
pedalboardAudioStream native components are present).