SPB Git

Repository Public

performance.md 18.7 KB 237 lines markdown

1# Performance23This document collects every performance figure that has actually been measured for ORIX DJ, with the machine, the build and the conditions of each measurement, and lists what has not been measured. No figure here is an estimate. The architecture behind the numbers is described in [audio-engine.md](../architecture/audio-engine.md), [deck-engine.md](../architecture/deck-engine.md), [mixer.md](../architecture/mixer.md) and [dsp.md](../architecture/dsp.md).45## Sources of the numbers67| Source | Produced by | Build |8|---|---|---|9| [`engine-benchmark.txt`](../reports/engine-benchmark.txt) | `orix-dj-bench bench` | release |10| [`real-music-analysis.tsv`](../reports/real-music-analysis.tsv) | `orix-dj-bench analyze <folder>` | release |11| Test log blocks `=== ORIX-SYNC ===`, `=== ORIX-AUTOMATION-TIMING ===`, `=== ORIX-RENDER-COST (debug build) ===`, `=== ORIX-ANALYSIS-TIMING ===` | `swift test --no-parallel` in `Packages/ORIXDJCore`, run on 2026-11-21 | debug |12| Two offline mixes | `orix-dj-bench mix` | release |1314Machine for all of them: Apple M5 Max (18 cores, 48 GB), macOS 27.0 (build 26A5425a), Swift 6.4.2. The benchmark header itself records "Apple M5 Max, macOS Version 27.0 (Build 26A5425a), 20.0 s of audio per case, single render thread, 48 kHz".1516## What "offline" means here1718Every figure in this document except where stated was obtained by offline rendering: `DJEngine.renderOffline` calls `RenderCore.render` in a loop from an ordinary thread of a command-line process or of the test runner. It is the same `render` function the Core Audio callback calls, but:1920- the thread is not a real-time thread. The operating system may preempt it at any moment, and the time it spends descheduled is included in the measured block time. The **maxima** in the tables below therefore include scheduler preemption and are not the worst-case cost of the code. Means and 99th percentiles are much less affected.21- there is no audio device, no device clock and no competing audio I/O;22- the machine was otherwise idle apart from normal background activity; no load was applied on purpose.2324**No live measurement with an audio interface was taken.** The benchmark tool has a `live` command (see below), but the report contains no output from it, and no multi-channel interface was attached to the development machine. Callback jitter, overloads under real-time scheduling, behaviour at small buffers on real hardware and round-trip latency are all unmeasured.2526## How the benchmark is produced2728The tool is the `orix-dj-bench` executable target of the core package ([`main.swift`](../../Packages/ORIXDJCore/Sources/orix-dj-bench/main.swift), [`Benchmarks.swift`](../../Packages/ORIXDJCore/Sources/orix-dj-bench/Benchmarks.swift), [`RealMusic.swift`](../../Packages/ORIXDJCore/Sources/orix-dj-bench/RealMusic.swift)). From `Packages/ORIXDJCore`:2930```sh31swift run -c release orix-dj-bench bench            # the report; optional argument: seconds per case (default 20)32swift run -c release orix-dj-bench analyze <folder>  # the TSV table for a folder of audio files33swift run -c release orix-dj-bench mix <a> <b> <out.wav> [preset]34swift run -c release orix-dj-bench devices           # list output devices with reported latency35swift run -c release orix-dj-bench live [seconds] [buffer]36```3738A debug build prints a warning at the top of the `bench` output. Its other commands, `docs` and `check`, concern ORIX Script ([automation.md](../architecture/automation.md)).3940`bench` runs, in order:41421. **Render cost** (`measureRender`). A 48 kHz engine is created with the requested buffer size. Each deck gets a synthetic track from `SignalSynth.track` at 44.1 kHz, so sample-rate conversion is part of every case. Decks are assigned through the crossfader, fader at −9 dB, low EQ at −4 dB, filter knob at 0.15; with key lock, the rate is 1.04. The "14 effects" cases add echo, flanger and compressor on each of the four channel racks and reverb and delay on the master rack. The master limiter is on in every case (it is on by default). After one second of warm-up, each block is rendered separately and its duration is taken from `EngineRenderState.lastRenderNanos`, which `render` measures itself with `mach_absolute_time` from entry to exit. The table reports mean, 99th percentile, maximum, the block's real-time budget (`buffer / 48000`), load (mean / budget) and the number of clipped blocks.432. **Effects**. Each of the 18 units is created, enabled, and fed 4000 blocks of 512 frames of white noise; the mean wall-clock time per block is reported. The table is in [dsp.md](../architecture/dsp.md).443. **Time stretching** (`measureStretch`). A 440 Hz sine at 48 kHz is played for 8 s with key lock at seven rates, limiter off. Pitch is measured from interpolated zero crossings after the first second; the residual is the energy that is not the fundamental at the measured frequency; playhead speed is the deck position after 8 s divided by 8.454. **Analysis**. One 5-minute 44.1 kHz stereo synthetic track is analysed once, timed with wall-clock time.465. **Automation scheduling** (`measureAutomation`). Two automations run for the whole duration on a 128 BPM click track with 256-frame buffers: one issues sixteen parameter writes on every beat, the other runs continuous ramps on a filter, the crossfader and a fader. The scheduler is ticked once per block by `AutomationHost.renderOffline`.4748## Render cost (release, offline)4950From `engine-benchmark.txt`. Times are per render call.5152| Case | Buffer (frames) | Mean (µs) | p99 (µs) | Max (µs) | Budget (µs) | Load | Clipped |53|---|---|---|---|---|---|---|---|54| 2 decks, EQ + filter | 64 | 2.8 | 10.8 | 179.0 | 1333 | 0.21 % | 0 |55| 2 decks, EQ + filter | 128 | 5.6 | 17.6 | 89.7 | 2667 | 0.21 % | 0 |56| 2 decks, EQ + filter | 256 | 10.8 | 25.7 | 109.2 | 5333 | 0.20 % | 0 |57| 2 decks, EQ + filter | 512 | 22.0 | 49.4 | 132.0 | 10667 | 0.21 % | 0 |58| 2 decks, key lock | 256 | 12.7 | 41.5 | 106.0 | 5333 | 0.24 % | 0 |59| 4 decks, EQ + filter | 256 | 18.6 | 39.8 | 178.9 | 5333 | 0.35 % | 0 |60| 4 decks, key lock, 14 effects, limiter | 256 | 61.2 | 124.7 | 396.8 | 5333 | 1.15 % | 0 |61| 4 decks, key lock, 14 effects, limiter | 64 | 15.3 | 48.8 | 173.7 | 1333 | 1.14 % | 0 |6263Reading the table:6465- The mean scales with the buffer size, so the load is roughly constant per configuration. The heaviest case measured uses 1.15 % of one core on this machine.66- The maxima do not scale with the buffer (179.0 µs at 64 frames against 132.0 µs at 512), which is consistent with them being dominated by preemption rather than by the work in the block, as explained above. In the heaviest case at 64 frames the maximum, 173.7 µs, is 13 % of the 1333 µs budget.67- With key lock the cost is uneven by construction: the stretcher synthesises a 1024-frame hop at a time, so a block that triggers a hop costs more than one that only reads the FIFO. This shows in the p99 of the key-lock case (41.5 µs against 25.7 µs without).68- These are results for one machine. No measurement exists on older or slower Macs.6970For reference, the test suite prints the same kind of figure from an unoptimised **debug** build running under the test runner (`renderCostFullLoad`: four decks with key lock, twelve channel effects, three master effects, limiter, 256-frame buffers): mean 3098 µs, maximum 69 046 µs, 58 % of the 5333 µs budget over 1875 blocks. This is not a performance result. It is quoted to show how much the optimiser matters and why the release benchmark, not the test log, is the reference; the test only asserts that more than 1000 blocks were rendered.7172## Time stretching (release, offline)7374From `engine-benchmark.txt`: 440 Hz sine, 48 kHz, key lock on.7576| Rate | Measured pitch | Error | Residual below the tone | Playhead speed |77|---|---|---|---|---|78| 0.84 | 440.002 Hz | +0.01 cents | 40.5 dB | 0.8396 |79| 0.92 | 440.014 Hz | +0.06 cents | 29.0 dB | 0.9213 |80| 0.96 | 440.015 Hz | +0.06 cents | 46.5 dB | 0.9612 |81| 1.00 | 440.000 Hz | +0.00 cents | 99.5 dB | 1.0000 |82| 1.04 | 439.985 Hz | −0.06 cents | 160.2 dB | 1.0388 |83| 1.08 | 439.989 Hz | −0.04 cents | 25.6 dB | 1.0804 |84| 1.16 | 440.000 Hz | +0.00 cents | 37.9 dB | 1.1584 |8586The pitch is held within 0.06 cents. The residual, which is everything in the output that is not the fundamental (amplitude modulation and splice artefacts of the overlap-add), varies strongly with the rate, from 25.6 dB to 160.2 dB below the tone, because it depends on how the splice period relates to the period of the test tone. A steady sine is a favourable and narrow test: it says nothing about transients, polyphonic material or stereo content, and nobody has listened to the stretcher's output. The method and its limits are described in [deck-engine.md](../architecture/deck-engine.md).8788The header of this section in the report also mentions "120 BPM clicks"; the click measurement is done in the test suite (`keyLockPreservesBeatTiming`, tolerance 12 ms), not in the benchmark tool.8990## Timing accuracy (debug, offline)9192From the test log of 2026-11-21.9394**Sync.** `syncMatchesTempoAndPhase` plays a 120 BPM click track on deck A and syncs a 126 BPM click track whose first beat is 80 ms into the file on deck B, then compares click onsets on the two output channels:9596```97=== ORIX-SYNC === mean 0.006628787878787879 ms, worst 0.020833333333333332 ms over 22 beats === END ===98```99100The worst offset, 0.0208 ms, is one sample at 48 kHz. The test's tolerance is 3 ms. The tracks are synthetic clicks with exact beat grids, so this measures the sync mechanism, not the accuracy of beat detection on music (for that see [analysis.md](../architecture/analysis.md)).101102**Automation.** `scriptActionsLandOnExactSamples` schedules deck starts and a pause on bar and beat boundaries from an ORIX Script and compares the started deck's clicks with the master deck's clicks:103104```105=== ORIX-AUTOMATION-TIMING === tracked 3 late 0 maxLate 0 samples; worst click offset 0 samples === END ===106```107108Three timed commands, none late, zero samples of offset. The test allows 2 samples and requires `lateEvents == 0`. It sets the scheduler look-ahead to 20 ms.109110**Automation under load** (release, from `engine-benchmark.txt`, 256-frame buffers):111112| Quantity | Value |113|---|---|114| Scheduler ticks | 3750 |115| Tick duration, mean | 2.5 µs |116| Tick duration, max | 343.9 µs |117| Timed commands | 687 |118| Late commands | 0 |119| Worst lateness | 0 samples |120| Dropped control events | 0 |121| Runtime errors | 0 |122123Two caveats. First, offline the scheduler is ticked exactly once before each block, so "0 late" shows that the scheduling arithmetic and the sub-block event splitting are exact; it does not show how the scheduler thread behaves when it competes for CPU in the running application, where it wakes every 4 ms under the Mach time-constraint policy. Second, the report's section title says "15 ms look-ahead", but `measureAutomation` does not set the look-ahead and the default of `AutomationHost.lookaheadSeconds` in the source is 0.03; the title is a fixed string and may not reflect the value in effect.124125## Analysis speed126127**Synthetic track.** One 5-minute 44.1 kHz stereo track:128129| Build | Time | Source |130|---|---|---|131| release | 0.294 s | `engine-benchmark.txt` |132| debug, single thread, best of 3 | 0.747 s | test log, `=== ORIX-ANALYSIS-TIMING ===` |133134Both runs returned 126 BPM (truth 126), a first beat at 0.081 s (truth 0.080) and G minor (truth G minor).135136**Real music.** `orix-dj-bench analyze` was run on 60 commercial tracks from the owner's library. The footer of `real-music-analysis.tsv` reads:137138```139# 60 files, 0 failed, 12449 s of audio analysed in 32.0 s (389× real time)140```141142The 32.0 s is the sum of the analysis times only. Decoding is timed separately per file (`decode_s`): the column sums to 29.2 s, with a range of 0.10 s to 2.48 s per file; analysis ranges from 0.05 s to 1.98 s per file. Files are processed one after the other on one thread. Decode time depends on the codec and on the file cache and was measured once. The accuracy of the results on these tracks is discussed in [analysis.md](../architecture/analysis.md); the table has no ground truth for them.143144In the application, analysis runs on a background queue one track at a time (`DJSession.analyzePending`), and a track that has no stored analysis is analysed during its first load onto a deck.145146## Latency147148### Output latency shown by the application149150The latency the application reports is151152```153output latency = device-reported latency + one buffer154```155156where the device-reported part is `AudioDeviceInfo.latencyFrames`, computed in [`AudioOutput.swift`](../../Packages/ORIXDJCore/Sources/ORIXDJEngine/AudioOutput.swift) as `kAudioDevicePropertyLatency` + `kAudioDevicePropertySafetyOffset` + the latency of the first output stream. It is displayed in two places:157158- the status bar, as "… ms out", from `AppModel.outputLatencyMillis` (`(latencyFrames + bufferFrames) / sampleRate`), in [`AppModel.swift`](../../App/Sources/App/AppModel.swift) and [`RootView.swift`](../../App/Sources/App/RootView.swift);159- Settings → Audio, as three read-outs: "Buffer latency", "Device latency (reported)" and "Total output latency", in [`AudioSettingsTab.swift`](../../App/Sources/Features/Settings/AudioSettingsTab.swift), with the note that Bluetooth devices add latency the system does not report.160161The buffer part is arithmetic: at 48 kHz, 64 frames are 1.33 ms, 128 are 2.67 ms, 256 (the default) are 5.33 ms, 512 are 10.67 ms.162163This figure is a computed value from what the device declares. It has not been compared with a physical measurement (loopback or microphone), and it leaves out the following, which follow from the code:164165- the master limiter's 5 ms look-ahead when the limiter is on (it is on by default);166- any additional buffering inside the HAL or the device beyond what it reports, including Bluetooth codecs;167- the time between a user action and the next render call: an untimed control event takes effect at the start of the next buffer, so up to one more buffer;168- the interface itself, which refreshes at 30 Hz, and MIDI input delivery.169170`orix-dj-bench devices` prints the reported latency of each output device, and `orix-dj-bench live` would open the default device with the master at −60 dB and report callback times measured on the real-time thread, scheduler tick gaps and automation lateness. No output of either command is part of the reports.171172### Other fixed delays173174| Element | Delay | Source |175|---|---|---|176| Parameter changes | ramped over at least 4 ms | `RenderCore.rampSamples` |177| Transport de-click | 4 ms decaying offset, audio not delayed | `DeckVoice` |178| Effect enable, disable, mix | 12 ms cross-fade | `EffectUnit` |179| Limiter (master or rack) | 5 ms look-ahead | `LimiterEffect` |180| Recording writer | drains every 40 ms (does not affect audio) | `Recorder` |181182## Memory183184### Decoded tracks185186A loaded track is held entirely in memory as planar 32-bit float stereo at the file's sample rate ([`TrackBuffer.swift`](../../Packages/ORIXDJCore/Sources/ORIXDJEngine/TrackBuffer.swift)): `byteSize = frameCount * 2 * 4`, that is 8 bytes per frame, whatever the source format or channel count.187188| File sample rate | Per minute | 5-minute track | At the 150-minute cap |189|---|---|---|---|190| 44.1 kHz | 21 168 000 bytes (21.2 MB) | 105.8 MB | 3.18 GB |191| 48 kHz | 23 040 000 bytes (23.0 MB) | 115.2 MB | 3.46 GB |192| 96 kHz | 46 080 000 bytes (46.1 MB) | 230.4 MB | 6.91 GB |193194(MB and GB are decimal: 10^6 and 10^9 bytes.) These values are computed from the format, not measured from the process. Consequences:195196- four loaded 5-minute tracks at 44.1 kHz hold about 423 MB of sample data;197- `TrackBuffer.maxSeconds` is 150 minutes; a longer file is refused with a message. A file at the cap is accepted, and the table shows what that costs. There is no check against available memory;198- a compressed file expands by the ratio between its bit rate and 2822 kbit/s (44.1 kHz) or 3072 kbit/s (48 kHz);199- background analysis decodes one more track at a time into its own buffer, released when that track is done.200201### Fixed allocations of the engine202203Computed from the constants in the code, for a 48 kHz engine:204205| Allocation | Size |206|---|---|207| Recording ring (`AudioRing`, 524 288 frames × 2 channels × 4 bytes) | 4.2 MB, allocated whether or not a recording is running |208| Delay or echo unit (2 lines of 262 144 samples) | 2.1 MB per unit |209| Beat repeat unit (ring of 262 144 frames plus a 4 s loop buffer, stereo) | about 3.6 MB per unit |210| Mix buffers (6 × 4096 floats) | 98 kB |211| Event queue (8192 slots) and pending list (512 slots) | well under 1 MB |212213The resident memory of the running application has not been profiled, and no measurement of waveform, library or interface memory exists.214215## Real automated mixes216217Two complete transitions between commercial tracks were rendered offline with `orix-dj-bench mix`, which decodes two files, analyses them, applies the suggested gain and key lock, starts the first deck, runs a preset script from the library (the preset turns sync on for the incoming deck), and writes the master output of the 48 kHz engine to a 16-bit WAV file.218219| Preset | Tracks | Result printed by the tool | Analysis of the rendered file |220|---|---|---|---|221| Bass Swap | a 124 BPM track into a 122 BPM track | deck B played at 124.00 BPM; 10 timed commands, 0 late; 0 clipped blocks; peak −6.99 dBFS | 124.00 BPM, tempo stability 0.98 |222| Eight Bar Transition | two 119 BPM tracks | 9 timed commands, 0 late; peak −3.71 dBFS | 119.00 BPM, tempo stability 0.98 |223224These runs show that the whole chain (decode, analysis, sync with key lock, script execution, mixing) completes on real material with exact command timing and without clipping, and that the tempo of the result is steady through the transition. **Nobody has listened to these two files yet.** Whether the transitions sound right, whether the beats of the two tracks are audibly aligned and whether key lock is acceptable on this material is not established by these numbers.225226## Not measured227228- Anything on the real-time thread with a real device: callback duration distribution, overloads, the smallest usable buffer, behaviour under system load.229- Physical output latency and input-to-sound latency (interface or MIDI controller to speaker).230- Any machine other than the M5 Max; Intel is not a target (arm64 only).231- CPU cost of parameter sweeps, of the first block after an effect bypass, and of 88.2 or 96 kHz operation.232- Aliasing of the cubic resampler and listening quality of key lock and of the effects.233- Memory footprint of the running application, energy use, and the cost of the Metal waveform renderer ([waveform.md](../architecture/waveform.md)).234- Long sessions: the longest continuous offline renders are the benchmark cases (20 s each) and the test and mix runs of a few minutes.235236See [testing.md](testing.md) for the test suites that produce the test-log figures and for how to rerun them, and [setup.md](setup.md) for building the package.237
Files main
Menu

Theme