# Dorota

An editor for ATS (Analysis-Transformation-Synthesis) spectral data in SuperCollider.

Dorota analyses audio into partial trajectories, shows them on an editable canvas, and
resynthesises the edited result. The analysis engine (z354) is a SuperCollider
implementation of the ATS pipeline rather than a wrapper around the ATSA binaries.

## Install

```supercollider
Quarks.install("https://github.com/Elvis-Budingensis/Dorota");
```

Recompile the class library, then:

```supercollider
Dorota.open;
```

If a previous copy of Dorota or the z354 classes sits in
`~/Library/Application Support/SuperCollider/Extensions/`, remove it first — duplicate
class definitions stop sclang from compiling.

## Editing

**PAINT** — sclang exposes no tablet pressure, so drawing speed stands in for it. Slow
strokes come out wide and loud, fast strokes thin and quiet; reference speed is around
1200 px/s, pressure range 0.18 to 1.0, full-scale amplitude from the PAINT-AMP slider.
Painted partials are exempt from the whistle-tone damping and stay audible even with no
audio file loaded. Every reversal of direction in time starts a new partial, so loops
appear as overlapping partials — an ATS partial is single-valued per time point and
genuine loops cannot be represented otherwise.

**SCRUB** — time-local rubbing of existing partial data.

**SPRAY** — airbrush that reveals partials masked in the original analysis.

## Structure

```
Dorota.quark          quark metadata
Classes/              compiled automatically by sclang
  Dorota.sc           entry point: paths, server options, load order, GUI
  ATSAnalyzer.sc      z354 analysis engine
  ATSPeakDetector.sc  peak picking
  ATSPeakTracker.sc   partial tracking
  ATSResidual.sc      residual = original - deterministic resynthesis
  ATSSynth.sc         resynthesis
  ATSWriter.sc        ATS binary output
  Z354Sound.sc        the analysed-sound data model
  DorotaAnalysisSettings.sc, DorotaFFTSelector.sc
Core/                 loaded at runtime by Dorota.load, not compiled
  Core_01..04, 06     helper layer (track building, import, sanitise, ATS I/O)
  Core_05             the GUI (~startATSSpearEditorV541)
  Core_z354_shim      playback wiring, plus stubs for unported features
  Core_z354_analyzer  ANALYZE -> z354 pipeline, writes .ats
  dorota_banner.scd   ASCII portrait
tools/check_quark.py  structural checks, run before tagging
HelpSource/           schelp documentation
examples/
```

The `Core/*.scd` files still define interpreter globals (`~startATSSpearEditorV541` and
friends) and are loaded into `topEnvironment` at runtime. That is deliberate for this
release: it keeps a working editor without rewriting 4300 lines of GUI code. The
`Dorota` class is the seam behind which that can be replaced incrementally.

## Known limits

- MIN/MAX-FREQ currently filter the display only. The z354 synth has `loFreq`/`hiFreq`
  ready, but the GUI sliders do not mirror their values globally yet.
- Transforms, session/project/batch handling, SMR and the tracking tools are no-op
  stubs in this build. The buttons report themselves and do nothing.

## Releasing

1. `python3 tools/check_quark.py` — must exit clean.
2. Test in a clean SuperCollider support directory (see below).
3. Bump the version in **both** `Dorota.quark` and `Classes/Dorota.sc`; the check
   script enforces that they agree.
4. `git tag 1.0.0 && git push --tags`
5. Add or update the line in
   [supercollider-quarks/quarks](https://github.com/supercollider-quarks/quarks/blob/master/directory.txt):
   `Dorota=https://github.com/Elvis-Budingensis/Dorota@tags/1.0.0`

Clean-room test — a compile error in a quark class stops sclang from starting at all,
and users will not know why:

```bash
mv ~/Library/Application\ Support/SuperCollider ~/Desktop/SC_backup
# start SuperCollider, Quarks.install("https://github.com/Elvis-Budingensis/Dorota"),
# recompile, Dorota.open
# afterwards restore the backup
```

## Credits and licence

ATS was developed by Juan Pampin. The partial-tracking and residual work follows
Pampin, Di Liscia and Moss; cubic phase interpolation after McAulay/Quatieri and
Smith/Serra (PARSHL).

GPL-3.0-or-later. See `LICENSE`.
