# Install SlowMySong Studio

The public download is a small source-and-launcher package for your own local
audio and video files. It does not include Python, Qt, FFmpeg or a YouTube
downloader. Your personal development copy retains its downloader separately.
Python 3.10 or newer and PySide6 6.8–6.x are required. Qt includes Chromium;
installing that dependency can download several hundred MB once, even though
the SlowMySong archive is small. Dependencies stay on your computer for later
app updates.

On first launch, a setup window shows what is ready, what is needed and the
commands to install it. Run the commands in your terminal, then choose
**Rescan** and **Open studio**. The checker never installs software for you.
If Python has no Tk support, the same checker opens in your browser using a
private address on your own computer. FFmpeg is optional: WAV export works
without it. Broad video playback, MP3/video export and additional audio formats
use FFmpeg.

Website downloads require agreement to the hobby project terms. A copy is
included in `legal/TERMS.txt` and alongside each archive. The desktop app does
not show a first-launch agreement dialog.

## Linux

Extract the `.tar.gz`, open the `slowmysong-studio` folder and run:

```sh
./slowmysong-studio
```

For a launcher in your application menu, run `./install.sh` in that same folder.
It installs the small app under `~/.local/opt/slowmysong-studio`; dependencies
are installed only when you run the setup commands. Python is usually already
available. If it is missing on Ubuntu/Debian:

```sh
sudo apt update
sudo apt install python3 python3-venv python3-tk
```

The checker provides graphics-library and FFmpeg commands for Debian/Ubuntu,
Fedora and Arch. Run commands matching your distribution. The default public
download is portable Python source; it does not have a frozen build's glibc
requirement. The Qt package you install has its own OS requirements.

## Windows

Extract the ZIP fully, then double-click **Start SlowMySong.cmd** inside its
`slowmysong-studio` folder. If Python is missing, the launcher displays this
PowerShell command:

```powershell
winget install --id Python.Python.3.12 --exact
```

Alternatively, use the [official Python installer](https://www.python.org/downloads/windows/).
Reopen the launcher after installing Python. Setup commands create a dedicated
virtual environment and install PySide6 there. For FFmpeg, the checker offers
`winget install --id Gyan.FFmpeg --exact`. If you install FFmpeg, close and reopen
the launcher to refresh its PATH.

## macOS

The source ZIP works on Apple Silicon and Intel Macs. Extract it and double-click
**Start SlowMySong.command** inside `slowmysong-studio`. Python is required; use
the [official macOS installer](https://www.python.org/downloads/macos/) or,
if you already use Homebrew, `brew install python`. Reopen the launcher
after installing Python. The setup checker provides the PySide6 commands and
offers `brew install ffmpeg` for optional codec support.

This release is an **unsigned source preview**, not a signed or notarized macOS
application installer. The previous `.dmg` preview was also unsigned and not
notarized, which can trigger the verification warning. A polished native macOS
release requires a Developer ID certificate and Apple's notarization service.
If macOS blocks a trusted download, Apple's documented per-app option is to
attempt opening it, then use **System Settings → Privacy & Security → Open
Anyway** if that option is available. Follow [Apple's instructions](https://support.apple.com/en-us/102445);
do not disable Gatekeeper globally. Managed Macs may disallow exceptions.

## Rescan later

To open the setup checker again, run your launcher with `--check-dependencies`,
or run `python3 -m desktop.bootstrap` from the app folder. For diagnostic output
without a window, run `python3 -m desktop.bootstrap --json` (on Windows,
`py -3 -m desktop.bootstrap --json`).

## Files and dependencies

Public packages store their library, exports and settings in your account's app
data directory, separate from the program:

- Linux: `${XDG_DATA_HOME:-~/.local/share}/com.slowmysong.studio`
- Windows: `%LOCALAPPDATA%\com.slowmysong.studio`
- macOS: `~/Library/Application Support/com.slowmysong.studio`

The isolated Python environment lives in that directory's `environment` folder.
Imported media you open remains at its original location; your library and new
outputs use the paths shown in the studio. Reinstalling the small program does
not overwrite your media. Use `--data-dir /path/to/folder` for a separate library.
Your personal Varispeed source copy uses its existing project `library` folder.

Verify checksums with `sha256sum -c *-SHA256SUMS.txt` (Linux),
`shasum -a 256 filename.zip` (macOS), or
`Get-FileHash filename.zip -Algorithm SHA256` (PowerShell).

Optional frozen installers remain a separate build option for distributors.
Their bundled dependencies make them much larger; no frozen installer is needed
for the lightweight release.