Pymss Studio

A local workspace for music source separation, workflows, batch processing, stem editing, and mix export.

简体中文 · Download · Community · Start here · pymss core

About

Pymss Studio brings the pymss music source-separation engine to a desktop workspace. Download models, import audio, run separation jobs, audition results, and edit stems in one application. Use it for vocal and instrumental extraction, instrument stems, audio cleanup, batch processing, speech transcription, and vocal-to-MIDI conversion.

Separation and editing run locally. Preparing runtimes, models, or optional components requires a network connection; downloaded models can then process local audio.

Features · Download · Quick start · Preview · Troubleshooting · Development

Features

Area	Capabilities
Source separation	Import audio, video, or folders; process batches; select model outputs, device, format, folder layout, and naming rules.
Model ensembles	Select multiple models and output stems, configure an ensemble algorithm and weights, and save the combined output.
Model library	Search by name, purpose, architecture, or source; switch card/list views; manage favorites, notes, resumable downloads, storage, and default inference parameters.
Custom models	Import weights and configurations for supported architectures and use existing models in the separation workflow.
Workflows	Arrange separation, audio processing, ensemble, and save steps in the simple editor; use the advanced node editor for flexible connections, parameters, and import/export.
Task queue	Track queued and running jobs, progress and logs; cancel or retry jobs and organize completed session entries.
Results and projects	Review output stems and processing parameters, audition audio, open output folders, and continue in the editor.
Stem editor	Multitrack waveforms, clip editing, transport, volume/pan, mute/solo, fades, track effects, recording, project persistence, asset relinking, and mix export.
Audio tools	Format conversion, audio inspection, SDR / SI-SDR, ASR, vocal-to-MIDI conversion, silence slicing, and audio merging.
Runtimes and settings	Manage platform-appropriate CPU, CUDA, ROCm, and MLX environments; configure download sources, proxies, concurrency, paths, language, zoom, and themes.

Available stems, parameters, and devices vary by model and runtime. Acceleration depends on the model, hardware, drivers, and task configuration.

Download and install

Choose a version on GitHub Releases, read its release notes, and check Assets. If GitHub is inaccessible, use a mirror linked in those release notes.

Note

The project is under active development and current releases include prereleases. Read the relevant release notes and back up important projects and settings before upgrading.

Platforms and runtimes

Platform / hardware	Runtime or package identifier	Notes
Windows x64, NVIDIA GPU	windows-x64-cuda	CUDA requires a compatible GPU and driver.
Windows x64, CPU inference	windows-x64-cpu	A starting point when GPU compatibility is uncertain.
Windows x64, supported AMD GPU	windows-x64-rocm	Check the selected release's GPU and driver requirements; ROCm has a narrower support range.
Windows x64, smaller initial download	windows-x64-online	Includes the bootstrap runtime; install the required inference environment after first launch.
macOS 14+, Apple Silicon	macos-arm64-mlx	Uses MLX. Download the DMG and drag the application into /Applications.
Linux x64	linux-x64-appimage	The release workflow builds an AppImage; check the selected release's Assets for availability.
Intel Mac	No dedicated release package	The existing MLX package targets Apple Silicon; source builds still require checking inference dependency compatibility.

Release packages include Python, so end users do not need to install system Python separately. The macOS DMG includes the fixed Python, PyTorch, MLX, and bundled core packages; first launch does not download another Python environment. Open Settings → Runtime to inspect the active runtime and update its core. Installing, switching, reinstalling, or deleting an entire environment in the application is available on Windows and Linux.

File types

File	Purpose
Windows *-setup.exe	Installer; application data defaults to the user directory.
Windows *.7z	Portable package. Extract the complete directory and run Pymss Studio.exe; keep its runtime and tools directories.
macOS *.dmg	Apple Silicon installation image.
Windows *-update.zip	Update package for an existing installation, rather than a first-time installer. Follow the corresponding release notes.
Split files such as *.part-000	Download every part and follow the release's SPLIT-ASSETS-README.txt to merge them before extraction.

If quarantine attributes prevent a macOS application from a trusted source from opening, apply this command to the installed application:

xattr -cr '/Applications/Pymss Studio.app'

Quick start

1. Finish onboarding. Choose language, theme, data directory, and runtime. The Online package needs to finish installing an inference environment.
2. Prepare a model. Open Models, download a model for the target source, or import a supported custom model.
3. Configure separation. Open Separate, import audio/video files or a folder, then choose the model, output stems, directory, and format. Start with the model's default parameters.
4. Run and review. Select Start Separation, monitor progress and logs in the task queue, and audition the finished stems or open Results.
5. Edit and export. Open a result in the stem editor, adjust clips, volume, pan, and effects, save the project, and use Export Mix to create an audio file.

For a repeatable processing chain, open or create a workflow under Workflows in a separate editor window, choose files or a folder on its input nodes and directories on its output nodes, then save and run directly in the editor. Follow node progress on the canvas; edits made during execution apply to the next run. A short input can help confirm the model, device, and outputs before a larger batch.

Preview

These previews show the main features in English and Chinese, with light and dark themes at 1920 × 1080. Click an image to view it at full size.

Feature	Light theme	Dark theme
Batch separation and output configuration
Model library and categories
Simple workflow editor
Advanced node workflows
Results and audio stems
Stem editing and mixing

Audio tools, settings, and operation dialogs

Feature	Light theme	Dark theme
Multi-model ensemble configuration
Custom model import
Mix export
ASR speech recognition
Vocal-to-MIDI conversion

Screenshots render the current Vue pages with isolated presentation data. Task progress, download states, and waveforms illustrate the interface and do not represent performance measurements.

Audio tools

Open Tools to use these utilities independently of the separation workflow.

Tool	Capabilities and input requirements
Audio conversion	Batch output to WAV, FLAC, MP3, or OGG, with sample rate, channel, and encoding settings.
Audio inspection	Read containers, audio streams, codec parameters, and metadata tags with FFprobe.
SDR evaluation	Align reference and estimated audio, then calculate per-channel SDR and SI-SDR. Requires corresponding reference audio.
ASR	Use FunASR presets or local models to generate TXT, JSON, and SRT. Supported languages vary by preset.
Vocal to MIDI	Extract pitch and note timing with GAME's native Torch model. Extract a complete GAME model archive, then select its model.pt.
Audio slicing	Analyze silence and export clips, with minimum-length, threshold, and boundary-silence settings.
Audio merging	Order a directory's files by name, modification time, or a regular expression, then export a WAV with consistent audio settings.

The optional FunASR component installs on demand; ASR models download and cache on first use. The ASR tool is currently unavailable on macOS. Download a model archive from the GAME release linked in the MIDI tool. Keep the complete extracted directory: model.pt requires config.yaml beside it, and language-conditioned models also require lang_map.json. Do not move the weights alone. Language, output, and parameter options depend on the selected tool and model.

Plugin marketplace

Open Plugins in the sidebar to browse and search the official catalog. Install and activate a Python runtime in Settings first. Install from source accepts a plugin name, a Git repository URL, or a local folder; repository subdirectories use URL#path/to/plugin.

The Installed tab shows loading errors, operations, and update checks. Marketplace plugins support update, dependency repair, and uninstall. Existing plugins in ~/.pymss/plugins (or PYMSS_PLUGINS_DIR) are also listed, with files and dependencies managed outside the marketplace. Plugins run Python code with your user permissions.

Sources and additional dependencies are stored in runtime-envs/plugins/<runtime-identity>/installed/ under the application data directory. Dependencies resolve against the active runtime with host versions constrained. Incompatible requirements fail without replacing the working plugin. Updates are staged and verified before activation. Each runtime has its own marketplace installations.

Run plugin operations opens Tools → Plugin operations. Plugins must contribute operations through setup(plugin), and the runtime must contain pymss operations support. Legacy capability or graph-node plugins may have no generic operations. Installation does not add dynamic nodes to the Studio workflow editor.

Data, runtimes, and updates

Data locations

Settings, models, outputs, projects, logs, and temporary files share a data root. Inspect actual paths under Settings → Data Directory; model and output directories can be configured separately.

Distribution	Default data root
PYMSS_STUDIO_DATA_ROOT is set	The supplied path takes priority.
Development binary run directly from Cargo target/debug or target/release	data/ in the project root.
Windows portable package with a pymss-studio.portable marker beside the executable	data/ beside the executable.
Regular installed / other release packages	.pymss-studio/ in the user directory, such as %USERPROFILE%\.pymss-studio on Windows.

The root defaults to settings/, models/, outputs/, editor-projects/, logs/, and temp/. On macOS and Linux, writable runtime state is stored in runtime-envs/ under this root: active-runtime.json selects the current core, .overlays/ contains core updates and their dependencies, and optional-packages/ contains separately installed components. On Windows, these paths remain under the selected runtime root's runtime-envs/, generally in python-runtime/runtime-envs/ beside the installation resources. The macOS base Python environment stays inside the application bundle.

Editor projects reference audio files by path. Back up the associated audio as well as the project. Relink missing assets in the editor after moving or deleting original outputs. Use the application's migration workflow when changing the model directory.

Updates and environment management

Open Settings → About for version and update information. Windows and macOS builds whose release channel supports in-app updates can check and install updates there. Use the release page for builds without automatic update support. On macOS, an application update replaces the entire .app, preserving user data; administrator authorization is requested if write permissions are insufficient. Move the app to /Applications before updating: updates are blocked from a read-only DMG or App Translocation location. A change to the fixed base runtime contract requires a manual installation.

Use Settings → Runtime to update pymss, pymss-core, and their compatible dependencies independently of the desktop application. Review the prepared version and dependency plan before confirming. Packages are installed into a new core overlay and activated only after validation; a compatible previous core can be restored when available. Updates that require replacing fixed accelerator components are rejected, preserving the active runtime. Dependency combinations are defined in python/runtime-manifest.json.

Optional components such as FunASR use their own directories, separate from core overlays. Installation checks compatibility with the current PyTorch version and accelerator backend. On Windows and Linux, uninstalling FunASR removes its separate component directory and any copy installed directly in the active environment; downloaded models are kept. On macOS, component operations preserve packages in the bundled base runtime; the ASR tool remains unavailable. Pip and Numba caches are stored under the data root's temp/ directory.

On macOS, deleting Pymss Studio.app removes the application and bundled runtime while retaining the user data root, including settings, models, outputs, and core overlays. Removing and reinstalling the app therefore reuses retained data. Custom model/output directories and .pymss-studio-previous-*.app update backups beside the application must be managed separately.

Troubleshooting

Problem	What to check
Model absent from the separation page	Only downloaded models that support inference appear. Check download status, model support, and runtime readiness, then refresh the model list.
GPU missing or inference fails	Confirm the active backend, GPU/driver support, and model compatibility. Compare with CPU inference and inspect task logs.
Insufficient GPU or system memory	Keep task concurrency at 1 initially. Reduce batch or chunk size where supported; parameter meanings vary between architectures.
Runtime or model download fails	Check download source, method, and proxy under Settings → Defaults. Runtime installation also offers a PyPI mirror selector. Retry after confirming connectivity.
ASR or MIDI cannot start	Check FunASR installation and ASR model source. For GAME, use the complete extracted directory and check for config.yaml and, where needed, lang_map.json beside the weights.
Missing project assets	Check whether audio files moved or were deleted, relink them in the editor, and save the project again.
Update fails or a new version behaves unexpectedly	Record version, package type, and errors; read the release notes. Back up projects and settings before manually installing a complete package.

With developer mode enabled, open Diagnostics → Logs to filter by source, level, or task. Studio, Worker, pymss, and external tools have separate source badges. Warnings and errors are highlighted, with expandable tracebacks, code locations, and context. Task, workflow node, download, and installation logs use the same presentation.

Launching the application from a command prompt or terminal also produces readable console logs. Supported terminals use colors for levels and sources; redirected output and NO_COLOR omit color codes. Application log files contain one JSON record per line, while historical text in cumulative logs remains readable without conversion.

Diagnostics → Generate diagnostic report writes latest-diagnostic-report.md with build/session details, recent page and tool visits, operation requests and outcomes, separation parameters, workflow batch/node correlations, task history and graph summaries, editor project/export summaries, model downloads, cached runtime probes, and update events. Requests are captured before validation or worker startup, preserving the selected feature and parameters when an environment is missing or process creation fails.

The report distinguishes observations from this process and saved snapshots, including their observation/save times. Generation does not rerun environment probes or scan media files. It retains at most 24 recent operations and 12 historical tasks, prioritizing active and failed tasks; fields, collections, store reads, and report sections have explicit limits and omission/unavailability notes. Request and configuration summaries use allow-lists and omit transcript text, audio contents, arbitrary graph text, and proxy addresses. Errors and log tails can still contain custom names and paths; review them before sharing.

Automatic error reports coalesce errors within a five-second interval and write the latest error and traceback afterward. Pending errors are flushed before normal application exit. Clearing logs cancels older pending reports.

If no window appears at startup, exit any existing Pymss Studio process, open CMD in the installation directory, and enable verbose logging before the interface loads:

start "" /b /wait "Pymss Studio.exe" --debug

To save console output, run start "" /b /wait "Pymss Studio.exe" --debug > "%TEMP%\pymss-startup.log" 2>&1. The flag enables verbose Studio and Worker logs for this process without changing the saved developer mode setting. A subsequent launch without the flag uses the original logging level. Exit an existing process before relaunching with the flag. On macOS and Linux, pass --debug directly to the application executable.

For unresolved issues, include application version and package type, OS version, GPU model, separation model, reproduction steps, and relevant log excerpts in GitHub Issues. Remove personal paths, proxy credentials, and other sensitive information from logs before sharing.

Development and verification

Prerequisites

• Node.js 22, matching CI, and pnpm@10.33.2.
• Rust stable / Cargo and Tauri's platform prerequisites: C++ build tools and WebView2 on Windows, Xcode Command Line Tools on macOS, and the appropriate WebKitGTK/system libraries on Linux.
• Python 3.12. Audio features use media tools such as FFmpeg / FFprobe; release scripts stage these tools for packaged builds.

git clone https://github.com/pymss-project/pymss-studio.git
cd pymss-studio
pnpm install --frozen-lockfile

For a first full desktop development session on Windows, prepare bootstrap Python, then install and activate an inference environment through onboarding or Settings → Runtime. Initial installation needs network access, and download size depends on the backend. The commands below prepare only the bootstrap interpreter. On Linux, install an inference environment through onboarding or Settings → Runtime. On macOS, prepare a compatible inference runtime separately or reuse a prepared bundled runtime. Download model weights separately in the model library.

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install "requests[socks]>=2.32,<3"
$env:PYMSS_STUDIO_PYTHON = (Resolve-Path .\.venv\Scripts\python.exe).Path
pnpm tauri dev

macOS / Linux:

python3.12 -m venv .venv
.venv/bin/python -m pip install "requests[socks]>=2.32,<3"
export PYMSS_STUDIO_PYTHON="$PWD/.venv/bin/python"
pnpm tauri dev

You can reuse an existing bundled runtime or activated environment. Overriding bootstrap Python does not force replacement of an active inference environment. Media features in development also need FFmpeg / FFprobe on PATH or in a prepared tools directory.

Commands

Command	Purpose
pnpm dev	Frontend server on port 1420 for UI development and browser previews.
pnpm tauri dev	Full desktop application with frontend hot reload and Rust / Python orchestration.
pnpm build	TypeScript checks and the frontend production build.
pnpm tauri build	Desktop build; runs the frontend build first. A complete inference runtime must be prepared separately.
pnpm test / pnpm test:frontend	Frontend logic tests.
pnpm test:python	Python Worker module tests.
pnpm test:rust	Rust backend tests.
pnpm test:all	Run the three layers sequentially after preparing their dependencies.

For documentation changes, verify content and links. Frontend changes should run relevant tests and pnpm build; Worker/backend changes should run the corresponding layer's tests. CI uses Node.js 22, Python 3.12, and Rust stable, and runs pnpm test:all plus the frontend build.

Python Worker debugging and environment variables

Use a dedicated Python 3.12 environment for standalone Worker debugging. Prepare compatible Torch and pymss dependencies for the selected backend first. python/requirements.txt describes Worker development dependencies; python/requirements-ci.txt describes CI test dependencies. Managed application environments follow the runtime manifest.

python python/worker.py --help
python python/worker.py env_info
python python/worker.py list_models --payload '{}'

These commands use the terminal's current Python interpreter, rather than automatically selecting the desktop application's active environment. Use the bundled or active environment's Python path when verifying a release package.

Variable	Purpose
PYMSS_STUDIO_DATA_ROOT	Override the application data root.
PYMSS_STUDIO_PYTHON	Override bootstrap Python. Without an override, the backend tries the bundled runtime, then system python on Windows or python3 elsewhere. Inference may still use an activated environment.
PYMSS_STUDIO_DEFAULT_OUTPUT_DIR	Worker output fallback when none is specified; the desktop application passes its configured output directory to the Worker.

Architecture, repository layout, and releases

Layer	Stack and responsibilities
Frontend	Vue 3, TypeScript, Vite, Pinia, Vue Router, Vue I18n, and Naive UI; workflow node editing uses LiteGraph.
Desktop backend	Tauri v2 and Rust for dialogs, process orchestration, persistence, updates, and windows.
Worker	Python JSON protocol for models, inference, workflows, and audio processing.
Separation engine	External pymss / pymss-core packages. This repository integrates the desktop application rather than implementing core separation algorithms.

flowchart LR
  UI[Vue / Naive UI] --> API[Tauri / Rust]
  API --> Worker[Python Worker]
  Worker --> Core[pymss / pymss-core]
  Core --> Audio[Separated stems]
  Audio --> Editor
  UI --> Editor[Stem editing and mix export]

Loading

.
├── src/                   # Views, components, stores, workflows, tools, and i18n
├── src-tauri/             # Rust backend, desktop configuration, and bundled resources
├── python/                # Worker, audio modules, and runtime manifest
├── tests/                 # Frontend/Python tests, manual checks, and fixtures
├── scripts/               # Runtime preparation and release checks
├── .github/workflows/     # CI and Windows/macOS release pipelines
├── installer/             # Windows installer resources
└── images/screenshots/    # English/Chinese light/dark screenshots

Windows releases prepare bootstrap Python and a backend environment, build the Tauri executable, stage the Worker/runtime/media tools, and create installers and portable archives. macOS releases prepare arm64 MLX and media tools before creating a DMG.

./scripts/prepare-python-runtime.ps1 -Variant cuda -InitialBackend cuda
./scripts/prepare-python-runtime.ps1 -Variant default -InitialBackend cpu

These are alternative runtime preparation examples; select one rather than running them sequentially. Preparation writes python-runtime/, requires network access, and involves large downloads. See the Windows and macOS workflows for complete staging, signing, validation, and asset splitting.

Future directions

• Continue improving Intel / AMD model compatibility, runtime validation, and packaging.
• Explore iOS / Android GPU and NPU inference. Mobile support is a future research direction; no mobile application release is currently provided.

Community and contributing

Use GitHub Issues for bug reports and GitHub Discussions for features and usage discussions. Chinese-speaking users can also join the Pymss Studio community group.

See CONTRIBUTING.md for contribution options and the current policy on external pull requests. Reproduction reports, compatibility checks, documentation, and shared usage experience help improve the project.

License

Pymss Studio is licensed under the GNU Affero General Public License v3.0. See LICENSE. Dependencies, model weights, and third-party tools retain their own licenses and usage terms.