The Windows setup assistant is adapted from the c64-3d-toolkit setup workflow, with the dependency list reduced to what audio-bitsqueezer actually uses.
From the project directory in PowerShell or Command Prompt:
.\setup-windows.cmd
.\run.cmd guiinstall.cmd and run.cmd --setup are aliases for the assistant. Setup works
before Python is installed. run.cmd gui and run.cmd --gui offer to run the
assistant when Python, the project environment/packages or FFmpeg are unavailable.
This prompt appears in the terminal before the browser UI opens. It requires
an interactive terminal and the shipped .cmd and .ps1 setup files.
After an accepted setup finishes, the launcher checks the dependencies again and continues with the original GUI arguments and working directory. Declining, cancelling, or a failed/incomplete setup stops startup. Redirected input never triggers an interactive install or an indefinite wait. If the setup files are absent, the launcher's existing Python-package setup and error guidance apply. The read-only doctor and help commands never offer system installations.
| Component | Required for |
|---|---|
Python 3.10+ with venv and ensurepip |
Launcher and project environment |
pip inside .venv |
Installing/checking project packages |
pydub, packaging, Python 3.13+ audioop-lts |
Normal CLI conversion and GUI; versions come from requirements/base.txt |
| FFmpeg 4+ and ffprobe | Audio decoding/resampling; both executables are checked by running -version |
| Git | Optional cloning and updates; unnecessary for running an extracted ZIP |
VICE cartconv |
CRT cartridge packaging |
VICE x64sc |
Optional emulator playback/feedback and audit |
64tass (64tass.exe; INI key tass) |
Optional rebuild of bundled C64 players/boot templates |
| ACME | Optional rebuild of the bundled EasyAPI driver |
| Analysis/audit requirements | Optional profiler, multi-pass and reSIDfp feedback |
The browser UI, ordinary digi conversion and PRG export require no C64 assembler or emulator. No Flask, Electron, Node.js or separate GUI package is required. The shipped web UI uses the Python standard-library HTTP server.
Setup probes the selected Python's version, venv, ensurepip and pip. A missing
pip is bootstrapped/repaired inside the project .venv using ensurepip.
Setup uses python -m pip, never an unrelated pip.exe from PATH. Requirements
and their Python-version markers are checked by the existing shared launcher.
Working environments are reused without reinstalling packages. A broken or
foreign .venv is reported; setup does not delete it automatically.
Use the exact Gyan full-build package from WinGet's winget source:
winget install --exact --id Gyan.FFmpeg --source wingetFFmpeg's download page links to
Gyan's Windows builds, which contain
ffmpeg.exe, ffprobe.exe and ffplay.exe. These are third-party Windows builds
linked by the project; FFmpeg itself publishes source code. The full build is
the existing repository default and avoids needing to choose codec subsets.
Compatible installations from other providers are kept.
The assistant first reuses working executables. If installation is selected, it
queries the exact package in the winget source, checks installed status, and
asks before installing a missing package. A failed status query is treated as
unknown, not as proof that the package is absent. Already registered packages
are kept; the assistant does not force upgrades/reinstalls. WinGet's installer
output remains visible, and its nonzero exit status is reported. WinGet checks
the package manifest's download hash; setup does not disable hash validation.
Other manual sources:
- Python for Windows: include pip and venv.
- Microsoft App Installer / WinGet.
- Git for Windows, if wanted for updates.
- VICE, if needed for CRT export or emulation.
The assistant does not install other package managers, Blender or 64tass. Optional VICE setup retains the existing launcher's separate confirmation.
.\setup-windows.cmd -FFmpegPath "C:\Tools\ffmpeg\bin"
.\setup-windows.cmd -PythonPath "C:\Tools\Python313\python.exe"
.\setup-windows.cmd -Check-FFmpegPath accepts ffmpeg.exe, its directory, or the parent containing bin.
Both executable version checks must succeed before either FFmpeg setting is
written. Explicit path options authorize saving those selections to
config/bitsqueezer.ini under [windows]. Other settings and comments are
preserved; the original file is kept as config/bitsqueezer.ini.setup-backup.
That backup is not overwritten on later runs. Configuration and backups stay
out of Git. Invalid INI syntax must be corrected before setup can update it.
run.cmd refreshes its child process PATH from the machine/user environment while
retaining the caller's session-only entries. FFmpeg discovery also checks WinGet's
user/machine Links and Gyan package directories, and tools/ffmpeg/bin or
tools/ffmpeg. No whole-drive scan is performed. If one audio executable has a
configured path, the other can be discovered beside it. A default command name
such as ffmpeg or ffprobe.exe still permits automatic discovery.
Explicit custom paths take precedence. Installing FFmpeg elsewhere does not fix
an INI that explicitly names a missing executable: select the new location using
-FFmpegPath or edit the relevant settings. Reopen the terminal before invoking
newly installed tools directly; the child launcher cannot update its parent shell.
Python discovery preserves the existing priority: BITSQUEEZER_PYTHON, project
.venv, configured Python, then installed Python discovery. To switch Python
versions, rename the old .venv first. Correct or unset a stale
BITSQUEEZER_PYTHON override as well. Explicit paths must identify executables,
not shell command strings. Relative configured paths are based on the project
root; input/output audio paths remain based on the caller's directory.
.\setup-windows.cmd -Help
.\setup-windows.cmd -Check
.\setup-windows.cmd -InstallGit
.\setup-windows.cmd -Analysis-Check runs the read-only doctor, returns a failing status for missing required
dependencies, and reports optional tools separately. It cannot be combined with
options that install or save configuration. -InstallGit adds Git to the checks;
-Analysis installs the analysis/audit requirements after core setup succeeds.
An explicitly requested optional installation can return an error without removing
the working core environment.
Normal non-GUI launches retain automatic project Python-package setup. Missing
FFmpeg reports the setup command and the exact manual WinGet command. The
original converter under --legacy retains its historical PATH requirements.
.\install.cmd --install-all
.\run.cmd gui --auto-install-missingThe first command checks/installs all program, analysis and Python test
dependencies, then exits. Equivalent commands are setup-windows.cmd -InstallAll,
setup-windows.cmd --install-all and run.cmd --install-all. This bootstraps
Python if necessary before using the shared project .venv installer.
The second command checks/installs the GUI's dependencies before opening the browser. Without the flag, GUI startup asks in the terminal. OS elevation may still ask for permission. No packages are installed into an activated Conda environment. Explicit tool paths are retained and reported if invalid. See dependency coverage and failures.
Existing WinGet GTK3 VICE is supported. x64sc -version may exit successfully
without sending a banner to the captured output streams. The shared check
uses that successful exit plus the same installation's cartconv banner; it
no longer prints Executable check failed: 0 for that case. A failure still
includes the selected path, exit status or timeout, and repair guidance.
Known user/machine WinGet directories are searched even with a stale PATH.
The selected emulator and its sibling cartconv are used consistently unless
explicit executable overrides request otherwise. A second VICE installation
is not downloaded to repair an existing selection. Any already downloaded
tools/vice copy is left intact.
After applying 0.14.4, use the same CMD wrappers from PowerShell:
.\install.cmd --install-all
if ($LASTEXITCODE -ne 0) { throw 'Dependency setup is incomplete; read the named failure above.' }
.\run.cmd guiSee dependency setup for probe scope and installation repair.