Changelog#
All notable changes to tanh-lib are documented in this file.
The format is based on Keep a Changelog, and the project adheres to Semantic Versioning.
Unreleased#
Added#
thl::dsp::utils::Mixer: mixes any number of buffer views into one, each input scaled by a gain from its weight.Mode::Sumtakes the weights as the gains;Mode::Mixnormalises them to their p-norm (set_p():k_amplitude1 for correlated inputs,k_compromise4/3,k_power2 for uncorrelated ones,k_peakinfinity), so only their ratios matter and a mix keeps its level while it glides. Weights (one at a time orset_weights()), p and the mode glide over a ramp time (20 ms by default);passes_only()tells when a settled mix is one input unchanged, so a caller can skip work. The output may be one of the inputs. Real-time safe afterprepare()(by @jstolberg). Tests:Mixer.*.thl::RCU::add_reader()/read_scope(reader)(core/threading/RCU.h): a reader slot (RCU<T>::Reader) owned by the RCU instance, not by a thread, so a host rendering on changing threads no longer allocates and locks on the audio thread. A slot has one user at a time, and one user must be ordered before the next by happens-before (the host’s own call order, a mutex, an atomic claim flag with acquire / release): nothing checks it. Tests:RCU.OwnedReaderProtectsAcrossChangingThreads,RCU.SlotPoolWithOneUserAtATimeProtects,RCU.SlotScopeIsRealtimeSafeOnAnUnregisteredThread.thl::RCU::stage_update()/stage_replace()andcommit()(core/threading/RCU.h): a publication in two steps, for a change that spans several RCUs (or an RCU and state of the caller) and must not stop half-way. A stage is the first half ofupdate()/replace(): it makes the next version and the room to retire the one it will replace, may throw, and then has changed nothing. It returns a move-onlyRCU<T>::Staged, which frees the version when it is dropped.commit(Staged&&)is the second half:noexcept, without an allocation, it publishes, retires and reclaims asupdate()/replace()do and blocks only where they block. Stage everything, then commit everything. Between a stage and its commit nothing else may be published in that RCU (asserted in debug builds; a release build still publishes, but may then allocate); the RCU holds no lock between the two calls, so that exclusion is the caller’s mutex. Tests:RCU.StageThenCommitIsUpdateAndReplace,RCU.ReadScopeAcrossCommitKeepsItsVersion,RCU.TwoRcusStagedThenBothCommitted, andRCUAllocation.*in a new executable,test_core_allocation, which replaces the globaloperator newto count the allocations of a call and to fail each one in turn.thl::TripleBuffer<T>(core/threading/TripleBuffer.h): a wait-free single-producer / single-consumer latest-value mailbox. Its slots and the two sides’ indices arek_cache_line_sizeapart, so it is at least six cache lines (768 bytes). Tests:TripleBuffer.*.thl::SeqLock(core/threading/SeqLock.h): the sequence counter of a wait-free seqlock over atomics. Tests:SeqLock.*.thl::core::uptime_ns()(core/Clock.h): the uptime clock of UITouch, NSEvent and host times on Apple platforms,steady_clockelsewhere.Sample playback as standalone components, usable without the granular voice or any parameter system (design notes:
docs/sphinx/sampler.md,slicing.md,pitch.md):dsp::sampler::SamplePlayer: a varispeed player / looper overSampleViews, with Start / End / Loop markers or an exact region. End before Start plays backwards, and moving a marker never moves the audible head. A loop wraps through a crossfade before End (or after the wrap when Loop has no room behind it), equal-power, or equal-gain when both ends sit on zero crossings. Other discontinuities (source switch, retrigger, one-shot end) are crossfaded through a pool of outgoing heads. Tuning lives inPlayerSettings;render()takes a span of alternative sources, andsources_changed()must be called when the host loads new audio (snapped markers are cached against a source’s address and length).Its building blocks:
SampleViewwithread_clamped/read_wrapped,LoopRegion,LoopMarkers(minimum span, zero-crossing snap, cache),ZeroCrossing.h, andLoopCrossfade.h(FadeCurve,plan_loop_fade).dsp::slicing::SliceMap: up to 64 slices in frames, trivially copyable for an audio-thread handoff, rescaled for sources of another length;SliceSteps.hfor the slice-space mapping andregion_from_steps;valid_normalized_boundsfor host edits.dsp::slicing::TransientSlicer: offline band-flux transient detection that picks N slices, refines boundaries against the audio and falls back to the grid; every threshold is inSettings.dsp::pitch::PitchBank: pitch-shifted, equal-length copies of a sample, one slot per semitone, built across worker threads with Signalsmith Stretch.build()/shift()take the sample rate explicitly and refuse a non-positive one. Signalsmith is fetched and linked privately, andtest/exportsforbids it in the export table.dsp::utils::mixdown: mono average of a buffer, for offline analysis.
dsp::granular::GrainEngineis usable standalone: it takes aGrainParamsblock, aHeadMode(Spray/Scan), a span of sources and planar output, and reports to an optionalGrainVisualizer.thl::dsp::analysis::SpectrumAnalyser: the curve of a spectrum analyser display, on top ofStftAnalyser, for a reader thread. Resolution (FFT 1024 to 8192, 75 % overlap), points spaced on a log axis (256 from 20 Hz to 20 kHz by default), channels averaged in power; without smoothing a point is its band’s largest bin (a sine keeps its level), with fractional-octave smoothing its band’s mean power; tilt in dB per octave around 1 kHz (4.5 by default), speed (rises at once, falls at most so many dB per second), freeze (holds the maximum), floor.read_from(SampleProbe&)drains a probe of the same channel count and starts the frames over after a discontinuity. A tilt change moves the held curve at once, a smoothing change starts it over; a maximum above Nyquist is clamped to it; a rejectedprepare()leaves it unprepared. One thread for everything (the curve is a view). A full-scale sine reads 0 dB at tilt 0. Tests:SpectrumAnalyser.*.thl::graph::Graph::add_probe<Probe>(node, ProbePoint, args...)/remove_probe(ProbeId)/probe(ProbeId): a probe watches a node’s input (its sources mixed) or output (after its processor and wet mix),graph_input()’s output orgraph_output()’s input, with the latency of that point; it never changes the signal or the graph’s latency. Live: no commit, no fade. The graph owns its probes (so one probe can never watch two places): it prepares them when added and with everyprepare(), resets them withreset(); when a newly committed version starts, the probes of its nodes, of the nodes that stopped running and ofgraph_output()start over (graph_input()’s see a continuous signal and go on), andremove_probe()/remove_node()delete them once the audio thread no longer uses them (at most the block in progress). The returned pointer is for reading. Up tok_max_probes_per_pointper point. Tests:GraphProbes.*, including probes added, used and removed while the audio thread runs.thl::dsp::probe: probes watch a signal without changing it.ProbeBasegets every block read-only throughprocess(block, latency_samples)(skipped while inactive,set_active()); it is not aBaseProcessorand never a graph node.LevelProbe: peak per channel (the highest since the reader last took it,take_peak()) and RMS over a one-pole window (300 ms by default), as atomics.SampleProbe: copies every block into anSpscRingBufferfor one reader thread (scope, analyser). Wherever the stream is not continuous (areset(), the probe coming back from inactive, samples dropped because the reader fell behind),read()skips what came before and reports a discontinuity, so the reader never joins samples across a gap. Readers must not read duringprepare()(hosts call it on the main thread). Tests:LevelProbe.*,Probe.*,SampleProbe.*.thl::core::SpscRingBuffer<T>(core/threading/SpscRingBuffer.h): a multi-channel lock-free single-producer / single-consumer ring of samples, e.g. from the audio thread to an analyser. The writer appends blocks and never waits: what does not fit is dropped and counted (dropped()); the reader reads what has arrived, oldest first, or only the newest (read_latest()), or skips. Capacity rounded up to a power of two; real-time safe on both sides (two atomic positions, no locks, no allocation afterprepare()). Tests:SpscRingBuffer.*, including one writer and one reader side by side.thl::dsp::fft::StftAnalyser: the analysis half of a short-time Fourier transform.push()takes samples in chunks of any size; every hop, once an FFT size has arrived, each channel’s newest frame is windowed (Hann, or 4-term Blackman-Harris for -92 dB sidelobes), transformed (RealFft) and handed to the virtualprocess_spectrum(channel, bins), scaled so a sine of amplitude A reads A at its bin (0 dB for full scale).reset()drops what was collected, so no frame spans a discontinuity. Allocation-free afterprepare(). Tests:StftAnalyser.*.thl::dsp::fft::RealFft: the FFT of a real signal of a power-of-two size (32 to 65536), unscaled forward (asnumpy.fft.rfft: N / 2 + 1 bins, a sine of amplitude A reads A · N / 2), inverse scaled by 1 / N, real-time safe afterprepare(). The backend is a build option,TANH_FFT_BACKEND(cmake/fft-backend.cmake):pffft(default, every platform; marton78/pffft v1.1.0 compiled in, BSD-like FFTPACK licence, NEON/SSE) oraccelerate(macOS, iOS: Apple’s vDSP). Both give the same bins. Tests:RealFft.*(against the DFT by its definition, round trip, Parseval), run on either backend.thl::dsp::utilshelpers, real-time safe:Decibels.h(db_to_gain(),gain_to_db(),power_to_db(), float or double, floored atk_min_db= -120 dB or a given floor),TimeConstant.h(ms_to_samples(),one_pole_pole(): exp(-1 / samples), 0 for no time) andParameterValue.h(ParameterRange,sanitised(): NaN to a fallback, the rest clamped;to_enum()).LimiterImpl,EqDesign,SvfCoefficients::magnitude_db()and the dynamics blocks use them. Tests:Decibels.*,TimeConstant.*,ParameterValue.*.thl::dsp::dynamics::CompressorImpl: a compressor and expander on the dynamics building blocks. Downward and upward compression and expansion (Mode), threshold, ratio (infinity limits or gates), knee, range; peak or RMS detector, stereo link (linked, average, dual mono), sidechain high-pass; attack, hold, release, auto release; lookahead up to 20 ms, reported aslatency_samples()(the gain moves before the delayed audio); makeup, auto makeup, and an internal mix for parallel compression.process_with_sidechain()keys it by an external signal. Meters:gain_change_db(),input_peak_db(),output_peak_db(). Parameters throughget_parameter_float(), read at every block position; their defaults and ranges ink_parameter_ranges(a NaN reads as the default). A link change hands the gain over, so no channel jumps to an old gain. Tests:Compressor.*.thl::dsp::dynamics::LookaheadLimiterImpl: a brickwall lookahead limiter. The gain each sample needs goes through a minimum over the lookahead, a release in dB and a moving average over the lookahead, the audio delayed by the lookahead minus one: no output sample above the ceiling, the gain alone gets it there (a hard clip catches rounding). Ceiling, input gain, lookahead up to 10 ms, release, link (linked or dual mono), true peak (4x, 97-tap interpolator, +12 samples of latency; holds the ceiling for content up to 0.44 fs).latency_samples()reports it. Meters:gain_reduction_db(),input_peak_db(),output_peak_db(). Defaults and ranges ink_parameter_ranges(a NaN reads as the default); a link change hands the gain over. Tests:LookaheadLimiter.*.thl::dsp::dynamics(header-only,include/tanh/dsp/dynamics/): the building blocks of a dynamics processor.GainComputer, the static curve in dB for the four modes (DynamicsMode: downward and upward compression, downward and upward expansion) with threshold, ratio (infinity limits or gates), quadratic soft knee and range;LevelDetector, a peak or one-pole RMS level as a power (a non-finite sample reads as silence; a mode change clears the window);StereoLink.h,link_powers()(StereoLink::Linked,Average;DualMonolinks nothing);GainSmoother, attack and release in the log domain (attack away from 0 dB, in either direction), hold, and an auto release with a slow second stage (switched on, it starts from the current gain). Tests:GainComputer.*,LevelDetector.*,GainSmoother.*.
Changed#
thl::graph::Graphmixes withdsp::utils::Mixer: a node’s sources (InputMix) and its dry and wet signals (MixLaw); a wet mix glide stays on its law’s curve, as before (by @jstolberg). What changes: the pace along the curve follows the weights’ linear glide instead of the wet mix’s (DryHeld a quarter of the way from 0 to 1: dry 1, wet 0.33 instead of 0.5);MixLaw::Compromiseis normalised to a 4/3-norm of 1, within 0.09 dB of before (still -4.5 dB at 0.5); a change of mix law glides from the old law to the new one along the Mixer’s normalisation instead of crossfading the two laws’ gains; a bypassed or fully wet node stays so when its mix law changes (Mixer::passes_only()ignores glides that change nothing). A delayed source now has a scratch buffer of its own (channels × block size), allocated atcommit(). Tests:Graph.AWetMixGlideStaysOnTheMixLawsCurve,Graph.AMixLawChangeLeavesABypassedNodeBypassed.thl::RCU::update()/replace()allocate the new version and, when the retired list is full, its growth, and nothing else. The sweep of exited threads’ reader nodes at the end of every publication built two vectors, one allocation or more per publication as soon as the RCU had a reader; it now unlinks the nodes in place.tanh/core/Numbers.hincludes<numbers>wherever the standard library has it (__cpp_lib_math_constants), so it can be included next to<numbers>.thl::core::LockFreeQueueandSpscRingBufferkeep their writer’s and reader’s positionsk_cache_line_size(128 bytes,core/threading/CacheLine.h) apart instead of 64: Apple Silicon’s cache lines are 128 bytes, so 64 still let them share one.sizeof(LockFreeQueue)grows by up to 3 · 64 bytes.SpscRingBuffer::read_latest()takes its window from one snapshot of the writer’s position.thl::dsp::utils::BandSplitterreads crossover parameters itself: the virtualget_crossover_parameter_float()(non-finite by default: the crossover keeps whatset_frequency()gave it) andread_crossover_parameters(), whichMultibandLimiterImplandStereoWidenerImplnow call instead of each repeating it. Overrides keep working.Breaking:
thl::dsp::analysis::AdaptivePeakPickResult’s members arem_peak_indicesandm_threshold(werepeak_indicesandthreshold): public data members carry them_prefix like those of every other struct, which.clang-tidyasks for and the merge queue now enforces. Migration: rename the two members where the result ofadaptive_peak_pick()is read.Licence: the adaptive peak picker (
include/tanh/dsp/analysis/AdaptivePeakPicker.h,src/dsp/analysis/AdaptivePeakPicker.cpp) is under the dsp component’s licence, AGPL-3.0 (LICENSE), not Apache-2.0. The two files were added to the dsp component with anSPDX-License-Identifier: Apache-2.0header and a README sentence to match, but the library is licensed per component and the dsp component never was Apache-2.0: only the core component is. The header and the README sentence are removed; like every other dsp file, the two carry no SPDX line.thl::audio_io::AudioFileWriter::write_to_file()takes its buffer view byconstreference (was by value), like the other functions that only read a view. Calls compile unchanged; the exported symbol changes, so code linked against a sharedtanh_audio_iohas to be rebuilt.CI:
clang_tidy resultis a required check, and theclang_tidyworkflow reports on pull requests too. A pull request gets clang-tidy over the.cppfiles it changes (all of them when it changes.clang-tidyor the workflow); the merge queue keeps the full sweep. Both check the translation units of the Linuxdesktop-debugbuild, i.e. the entries of its compile database undersrc/andtest/, no longer every.cppfile there: a source of another platform (RealFftAccelerate.cpp) was analysed with a borrowed compile command and failed on a header Linux does not have. The sweep’s findings onmainare fixed (see the two entries above; the rest changed no interface).CI: the
coverageworkflow runs in the merge queue instead of on every push tomain, so the commit is measured before it lands. It stays a non-required check. Cache warming and the docs deployment stay on push tomain.
Fixed#
Graph: a node that turns the phase (itsprocess_with_dry()dry signal is not its input, e.g. a crossover) no longer steps when its wet mix reaches 0 or leaves it. The bypass passes the plain sources, while a blend’s dry signal is the phase-matched one; the switch between the two came at the end of the fade out and at the start of the fade in. The dry signal now glides between them with the wet mix (before the dry delay, so its history stays continuous), and the node is bypassed only once it has. Test:Graph.ANodeThatShiftsThePhaseGlidesIntoBypassAndBack.thl::RCU: read scopes on one thread or reader slot nest; closing an inner one freed the outer one’s version. Test:RCU.NestedReadScopesKeepTheOuterVersion.thl::RCU: destroying an RCU while a thread that read it still runs no longer frees that thread’s reader node under it (the thread wrote into the freed node on exit, and a new RCU at the same address reused it unseen by its writer). Whichever of thread and RCU goes second frees the node; a thread’s next registration frees what destroyed RCUs left in its registry. Tests:RCU.ThreadOutlivingTheRcuFreesItsNode,RCU.NewRcuAtADestroyedOnesAddressRegistersAnew,RCU.ThreadRegistryDropsDestroyedRcus.thl::RCU: destroying an RCU on a thread whose reader registry was already destroyed (an RCU with static storage duration that the main thread read, or one owned by athread_localconstructed before the thread’s first read) looked a node up in the destroyed registry: undefined behaviour, a segmentation fault at exit with libc++ (macOS, iOS, Android).~RCUno longer touches thread-local state; the destroying thread’s own node is freed like any other live thread’s, at that thread’s exit or its next registration. Test:RCU.DestroyedAfterItsThreadsRegistry(fails without the fix on libc++ only).thl::RCU::update()/replace()could throwstd::bad_allocwith the new version already published: the retired list grew, and the reader-node sweep allocated, behind the pointer swap. They now make every allocation first, so they publish, or throw and nothing has changed. An allocation failing in that sweep could also free the nodes of exited threads while they were still linked in the reader list; the sweep no longer allocates. Tests:RCUAllocation.UpdateAndReplaceThatCannotAllocateChangeNothing,RCU.DeadNodeSweepKeepsEveryLiveReader.thl::dsp::utils::LimiterImpl: a NaN threshold, attack or release made its gain, and so its output, NaN for good (and with itMultibandLimiterImpl’s bands). A NaN now keeps the parameter’s last value; the threshold is clamped to [-120, 24] dB, the times to [0.01, 60000] ms.process()isTANH_NONBLOCKING_FUNCTION. Test:Limiter.NanParametersKeepTheirLastValue.
0.5.0 - 2026-11-01#
Added#
tanh_add_core_library()(cmake/core-library.cmake): the core component as a library of the calling build,tanh_add_core_library(<target> SOURCE_DIR <tanh-lib> ABI_NAMESPACE <ns> [STATIC | SHARED] [LOG_COMPILED_MAX_LEVEL <AUTO | 1..4>] [WITH_JOURNALD] [ALIAS <name>]), with the sources, include directories, public definitions, platform libraries, symbol policy and version properties of the core; tanh-lib’s owntanh_coreis defined through it. An embedder that must not share a core with its host (anira) fetches tanh-lib under its own FetchContent name, populate-only, includes that tree’scmake/core-library.cmakeand builds a private core in a namespace of its own, e.g.tanh_add_core_library(anira_tanh_core ... ABI_NAMESPACE anira STATIC): the host’stanh_coreand the private core coexist in one build and one process. The file has no include guard; include the copy of the tree you build right before the call. Sanitizers and install rules stay with the caller. Seedocs/sphinx/symbol_visibility.md.TANH_ABI_NAMESPACE(defaultAUTO, which isv<major>_<minor>of the version from git): the inline namespace of every declaration.tanh_add_core_library()writes it asTHL_ABI_NAMESPACEinto a generatedtanh/core/AbiNamespace.hin the library’s build tree, which is in the core’s public include directories and is installed with the core, so every consumer compiles against the value the library was built with.scripts/abi-namespace.py: rewrites everynamespace thl...opener and closing comment to the ABI namespace and adds the include; idempotent,--checkfor CI. Re-run it after a rebase that brings in new files.test/abi-namespace(CTest, Linux, macOS, Windows):abi_namespace_symbols_<library>checks with nm / dumpbin that every symbol a library defines inthllies in its ABI namespace and none of tanh-lib’s lies at global scope (the toolchain’s own, such as libc++’s ABI-tagged::abs, MSVC’s global<cmath>overloads or the sanitizers’__rtsanhelpers, are exempt);test_abi_namespacelinks a second core library (tanh_core_b, namespacetest_b) besidetanh_coreand shows separate logger levels, configurations and callbacks;abi_namespace_sourcesruns the script’s--check. The install consumer prints the installed namespace.thl::dsp::fx::StereoWidenerImpl: a multiband stereo widener. Mid and side are split by Linkwitz-Riley crossovers (BandSplitter), each band’s side scaled by its width (0 mono, 1 unchanged, up to 2), the mid only through the crossovers’ all-passes, so mid and side stay in phase. Mono compatible whatever the widths (L + R is the mid signal through the all-passes); two bands with band 0 at width 0 is mono bass below the crossover. No latency; widths glide over 20 ms;process_with_dry()gives the input through the same all-passes, phase-matched. Widths throughget_band_parameter_float(), crossovers throughget_crossover_parameter_float()(orset_frequency()), read at every block position. Anything but stereo passes unchanged. Tests:StereoWidener.*.tanh::Graph(TANH_BUILD_GRAPH, off by default, on in every preset but wasm; by @jstolberg):thl::graph::Graph, aBaseProcessorofBaseProcessornodes. Edits on the control thread take effect atcommit(), handed to the audio thread with a fade; nested graphs, per-node input mix and wet mix,collect_garbage(). Latency compensation: the faster inputs of every merge and a node’s dry/bypass path are delayed, the graph holds silence after a commit until every delay is ready. It never pads: its output has the least latency its nodes allow (max_latency_samples()only sizes the delays), andcommitted_latency_samples()gives the latency the committed version will have, for the host right aftercommit()(a node whose maximum changed since the last commit counts at it until it runs). A node whose latency rises above the maximum it had at the last commit (or a nested graph that committed on its own) is compensated at that maximum until the graph containing it commits. A bypassed node coming back isreset(). Merges sum their sources by default (InputMix::Sum, orAverage). Per node,set_mix_law()chooses how the wet mix sets the dry and wet gains (MixLaw::Linear, the default,ConstantPower,Compromiseat -4.5 dB,Parallel,DryHeld), live, a change crossfading over 20 ms. Tests:test_graph(including edits and commits against a running audio thread),benchmark_graph.BaseProcessor::latency_samples()/max_latency_samples()/set_latency_samples()/set_max_latency_samples(): a processor reports its latency (by @jstolberg).thl::dsp::utils::DelayProcessor: an integer delay that crossfades linearly when the delay changes, and can keep its history without changing its input (by @jstolberg). Tests:DelayProcessor.*.BaseProcessor::process_modulated()takes the buffer’s position in the block (modulation_offset, default 0), so a caller that runs a block in parts, such as a graph, has its nodes read modulation at the block position.BaseProcessor::reset(): clears what a processor holds from the audio it processed, keeping its settings; real-time safe, does nothing by default.LimiterImpl,ParametricEqImpl,StereoFDNandDelayProcessorimplement it.thl::dsp::filter::ParametricEq: a parametric equaliser of up to 8 bands in series for any number of channels, each band a Peak, Notch, LowShelf, HighShelf, LowCut or HighCut (12 dB/octave). One trapezoidal state-variable filter (Cytomic) per band and channel. Every change of a band or of the design ramps its coefficients over 10 ms, so automation and a dragged band do not click; a flat or disabled band costs nothing, also when a field it does not use changes. Out-of-range and non-finite settings are clamped or replaced;prepare()keeps the bands.response_curve()andlog_frequencies()give the settled curve to plot, from the caller’s settings, on any thread. Real-time safe afterprepare(). Tests:ParametricEq.*.thl::dsp::filter::ParametricEqImpl:ParametricEqas aBaseProcessor, its parameters read throughget_parameter_float()(the design) andget_band_parameter_float()(type, frequency, gain, Q, enabled per band), so State and Modulation drive it. Tests:ParametricEqImpl.*.EqDesign.h:EqBand,design_band()andanalog_response().EqDesign::Matched(the default) follows the analogue prototype up to Nyquist: poles by impulse invariance, zeros fitted to the prototype’s magnitude (Vicanek, “Matched Second Order Digital Filters”, 2016, for the peak and the cuts; the shelves fitted at DC, their frequency and Nyquist up to Q 2, bilinear above, where the fit would miss a resonant shelf’s bump).EqDesign::Bilineargives the RBJ cookbook’s curves. Tests:EqDesign.*.SvfCoefficients.h:SvfCoefficients(Cytomic’s g, k, m0 to m2, with the exact response and the conversion to and fromBiquadCoefficients),SvfState,SvfTickandSvfRamp(click-free coefficient ramps), header-only, for any filter built on the trapezoidal SVF. The coefficients, states and per-sample gains are double: low bands at high sample rates stay at the float output’s own noise floor. Tests:SvfCoefficients.*.ConstellationReverbImpl::set_shimmer_position(): where the shimmer pitch-shifts the tank.Feedback(the default, unchanged) shifts each half’s output, so the shimmer is heard after a round of decay and builds with a long decay;Inputshifts each half’s input, the fresh input and the feedback together, so it is heard on the first pass, also with a short decay. Tests:ConstellationReverb.*.thl::core::BufferOperations: header-only static helpers on the samples of buffer views,copy(destination, source)andadd(destination, source), in every channel.sourceis aConstBufferView, so writable views andBuffers work too. Both views must have the same channels and samples (asserted) and must not overlap. Real-time safe.BufferViewitself stays a pure view. Tests:BufferOperations*.dsp::filter::Butterworth: header-only, per-sample low-, high- or all-pass (Butterworth::Response) of order 1–4: a 1st-order TPT section and trapezoidal SVF sections (SvfTick), states in double, so a low cutoff at a high sample rate stays at the float output’s own noise floor. The staticprewarp(f, fs)limits the cutoff to [1 Hz,k_max_frequency_ratio(0.497) · fs], a non-finite one to 1 Hz;process(x, g)takes the prewarped gain, so filters at the same frequency share onetan(). Real-time safe afterprepare(). Tests:Butterworth.*.dsp::filter::LinkwitzRiley: crossover of even order 2–8, two Butterworths of half the order per band.process_low()andprocess_high()can be called separately, also withg. LR2 and LR6 invert the high band, so low + high is an all-pass at every order. Tests:LinkwitzRiley.*.dsp::utils::SmoothedValue::is_smoothing(): whether a glide is in progress.dsp::utils::BandSplitter: an abstractBaseProcessorthat splits a signal into N bands with N − 1 Linkwitz-Riley crossovers in series. A derived processor calls the protectedprocess_band()for bands 0 to N − 1, in order, every block (asserted). The bands sum to the input through the all-passes of every crossover, so their sum before processing is the dry signal.set_frequency()clamps between the neighbouring crossovers and below Nyquist, and glides per sample over 5 ms; the prewarped gain is computed once per crossover and sample and shared by all its filters. The requested frequencies are kept, soprepare()at another sample rate clamps from them again; a non-finite one is ignored.set_frequency()blocks one crossover at its neighbours;set_frequencies()sets them all at once, independent of any order: crossing requests are sorted, so a crossover sweeping past another hands over continuously.reset()clears the crossovers. Tests:BandSplitter*.dsp::utils::MultibandLimiterImpl: oneLimiterImplperBandSplitterband, summed. Band count and order are constructor arguments; a derived class gives every band its threshold, attack and release throughget_band_parameter_float().process_with_dry()writes the sum of the bands before limiting, which matches the output below the thresholds (the limiters add no latency).reset()also releases the limiters. The crossover frequencies can come fromget_crossover_parameter_float(), read at every block position and applied together withset_frequencies(), so State and Modulation drive them like the bands’ parameters (non-finite, the default:set_frequency()decides). Tests:MultibandLimiter.*.BaseProcessor::process_with_dry(buffer, modulation_offset, dry): also writes the dry signal, the input with the phase response ofprocess()but without its effect, so that wet and dry can be blended. It is computed in the same pass, so it follows the same smoothing and modulation.dryis output-only; an emptydrymeans no dry signal. It is undelayed: a processor withlatency_samples()leaves aligning it to whoever mixes it (a Graph delays a node’s dry path by it). The default copies the input intodryand callsprocess(buffer, modulation_offset): override it ifprocess()changes the phase.process_modulated_with_dry(buffer, dry[, offset])andprocess_modulated_with_dry(buffer, change_points, dry[, offset])split both at the same change points. Tests:BaseProcessor.*.TANH_LINK_COMPILE_COMMANDS(default OFF; ON in thedesktop-*,macos-x64-*,android-*andwasm-releasepresets): a top-level configure linksbuild/compile_commands.jsonto its tree’s database (tanh_link_compile_commands, tanh-tooling v0.3.0), so clangd follows the tree configured last, the wasm tree included.
Changed#
Breaking: every declaration of every component lives in the inline namespace
thl::<ns>:thl::v0_5in this release,v<major>_<minor>of the version by default (each opener readsnamespace thl::inline THL_ABI_NAMESPACE::core {). Code keeps spellingthl::..., but every mangled name changes (_ZN3thl4v0_5...,...@v0_5@thl@@), so everything built against tanh-lib must be rebuilt. Two tanh-lib copies with different namespaces — a host’s and a plugin’s, a host’s and anira’s private core — no longer share code or state in one link; before, static archives on macOS, iOS and Windows gave both sides whichever copy the link order picked, and the header-only code merged by name on every platform. Migration: code that forward-declares a tanh-lib type itself (namespace thl { class State; }) declares a second, different type, which is ambiguous next to the header and does not link without it: include the tanh-lib header instead. A consumer built outside CMake needs the installedtanh/core/AbiNamespace.hon its include path (it sits next to the other core headers).Breaking: the Net component’s Objective-C download delegate is
TanhDownloadDelegate_<ns>(wasTanhDownloadDelegate): Objective-C class names are global to the process, so two copies of Net in one process no longer clash in the runtime.The API reference is generated with the ABI namespace filtered out (a Doxygen
INPUT_FILTER), so it documentsthl::core::Loggeras before.Graph: a node’s wet/dry blend takes its dry signal from the node (process_modulated_with_dry()), phase-matched to its output, and delays it by the node’s latency as before; a node that shifts the phase (a crossover, a multiband processor) no longer combs at a partial wet mix. A nested graph’s dry signal is still its input. Tests:Graph.ABlendOfANodeThatShiftsThePhaseUsesItsPhaseMatchedDrySignal.BaseProcessorhas the new virtualprocess_with_dry(), so its vtable changed: code that derives from it or calls it across a shared library must be recompiled.BaseProcessorholds its latency (two atomics), has a copy constructor and copy assignment and the virtualreset(): code that derives from it must be recompiled.StereoFDN::reset()andDelayProcessor::reset()now override it.process_modulated()no longer callsprocess()for an empty buffer.Shared tooling pinned to tanh-tooling v0.3.0 (
.clangd,cmake/tanh/,lint.yml)..clangdnow readsbuild/compile_commands.jsoninstead ofbuild/desktop/Debug/: reconfigure a development preset once to create the link. For the wasm tree, start clangd with--query-driver=**/em++(seedocs/sphinx/contributing.rst, “Shared tooling”).
0.4.0 - 2026-09-21#
Added#
thl::core::RingBuffer<T>: strided block calls,push_block(channel, data, count, stride),pop_block(channel, data, count, stride)andpeek_past_block(channel, data, count, stride). They read or writedata[0],data[stride], … and are exactlycountper-sample calls over that run, so one channel of an interleaved host buffer (data = interleaved + c,stride = num_channels, any channel count) moves between the host and the ring without a de-interleaved copy in between. A strided pop leaves the elements between the strided ones untouched and value-initialises what the ring cannot deliver; an oversized strided push keeps the tail of the run;stride == 1is the existing call (twostd::copy_nsegments). None of them allocates. Tests:RingBufferStrided.*(differential against the per-sample calls for 1, 2, 3 and 6 interleaved channels across the seam).Netcomponent (tanh::Net,TANH_BUILD_NET, off by default) — delivery of versioned file sets over HTTPS, for shipping model or sample packs that are too large to bundle.thl::net::HttpClient— GET to a file or a string,Rangeresume, progress with cancellation, and cancel from another thread. Backends are platform-native (NSURLSessiontoday) rather than a vendored TLS stack, so certificate validation uses the OS trust store and there is no CA bundle to ship or rotate inside a released plugin. Platforms without a backend reportHttpStatus::Unsupported;HttpClient::supported()lets a caller check once rather than per transfer. Windows, Linux and Android backends are not written yet.thl::net::Sha256— FIPS 180-4 in plain C++, streaming and whole-file, withmatches_hexthat rejects malformed input rather than trusting it. Plain C++ rather than OS crypto so the component needs one platform matrix (HTTP) and not two.thl::net::AssetStore— verified, atomic install of a caller-described file set into<root>/<id>/<version>/. The completion marker is written last, so a directory without it is a partial install thatis_installed()refuses andprune_partial()clears. Ids, versions and file names from a server are validated against path traversal. A failed install resumes without re-fetching files that already verify.The component knows nothing about manifests, models or packs: the caller supplies
{id, version, files:[{url, name, size, sha256}]}.Off by default so nothing embedding
tanh::Coreinherits a network stack.
Tested against a loopback HTTP server rather than a live endpoint — the failures worth covering (a well-formed response carrying wrong bytes, a declared length that is never delivered, a server ignoring
Range, cancellation mid-transfer) cannot be produced on demand against a real bucket. OneDISABLED_test fetches over real TLS when run with--gtest_also_run_disabled_tests.
Fixed#
dsp::granular::GrainProcessorImpl: volume modulation stepped the output.VoiceParams::m_volumeis a per-sub-block constant and was applied raw, so it was the only unsmoothed term in the voice gain (the ADSR already moves per sample) — a hard modulation step, such as a square LFO swinging both rails in one sample, reached the output as a discontinuity. The voice gain now ramps volume overk_volume_smoothing_duration(5 ms), seeded to the current level inprepare()and again at note-on so a voice starts at its level instead of sliding up to it.
Changed#
Breaking,
dsp::granular: the voice internals were split into the components above. Hosts that subclassGrainProcessorImplmust change the following:SlicerEnabled,LoopEnabledandLoopSnapmoved to the end of theParameterenum. Hosts that serve parameters by name are unaffected; tables indexed by the enum’s numeric value must be reordered.read_slice_map()takes adsp::slicing::SliceMap, which is frame-based, instead of the old normalised 16-slicegranular::SliceMap. Build it withSliceMap::from_normalized(bounds, total_frames).prepare()’ssamples_per_blockis now used: it sizes the player’s scratch.granular::SamplePlayer,SampleReader,SampleRegionandSliceMapare gone; usesampler::SamplePlayer,sampler::SampleView,sampler::LoopRegionandslicing::SliceMap.GrainEngineno longer takes aSampleReaderandVoiceParams: see the new API above.HeadPolicyreadsHeadInputs.The
k_player_*andk_*_varispeedconstants moved intosampler::PlayerSettings.
The Sample head now renders source channels and the voice applies the channel mode afterwards (
channel_mixer::mix_head). Grain output is bit-identical before and after the split; Sample-mode output differs by at most 1.2e-7 of full scale, from floating-point reordering.TANH_WITH_DOCSnow does something — it adds thesphinx-docstarget — and therefore defaults to OFF (it was ON and inert). A docs-enabled configure requires Doxygen and Python 3; consumers that already set it OFF are unaffected.dsp::granular::SamplePlayer: the equal-power crossfade reads a table instead of callingsin/cosper frame — a block fading the live head plus four outgoing tails wanted five transcendentals per frame. Becausecos(t * pi/2) == sin((1 - t) * pi/2), one quarter-sine table sized to the fade length inprepare()serves both directions, indexed straight by the integer fade counter: exact at every index, so the crossfade values are unchanged bit for bit.dsp::granular::GrainProcessorImpl: the voice gain pass skips the mode-fade ramp when the fade is already parked on its target, which is every block outside a mode switch. Same output, two fewer compares and a store per frame.
Added#
Documentation: a Doxygen → Breathe → Sphinx site under
docs/(the same pipeline as anira), published to https://tanh-lab.github.io/tanh-lib/ by the newbuild_docs_and_deployworkflow on every push tomain.just docsbuilds it locally. The API reference is generated frominclude/tanh/; the README’s design notes (symbol visibility,InputEventQueueevent spreading, the Android Bluetooth SCO notes) moved into the docs and the README is now a short entry point. Doxygen comments in the audio-io and state headers were corrected on the way (@paramnames that no longer matched the parameters,@sectionlabels reused across classes, a@copydetailsthat copied the wrong overload).dsp::granular: reverse playback from the markers alone — End before Start makes Start the entry and End the exit, so the Sample head runs backwards (re-entering at Loop) and Loop-mode grains scan and play backwards.SampleRegionkeeps ascending bounds plusm_reverseand mirrors only the read position (physical()), so the loop floor, crossfade pool and region-shrink logic are unchanged. Grain reads wrap below zero.dsp::utils::MorphWindow: a bank of eight grain windows (Rectangle, Trapezoid, Half cosine, Triangle, Hann, Gaussian, Narrow, Impulse) morphed by a continuous shape value — integers land exactly on a shape, fractions blend the neighbours — and skewed by a tilt in [-1, 1] that moves the peak by warping time around it. One shared instance, 512-point tables, peak 1, silent end points.GrainProcessorImplreads two new parameters,GrainWindowShapeandGrainWindowTilt(subclasses must serve them); a grain keeps the window it was born with.dsp::granular::GrainProcessorImpl: engine modes —EngineMode::GranularPosition(grains sprayed around a parkedPositionwithSpray/Tilt),EngineMode::GranularLoop(previous scan behaviour) andEngineMode::Sample(one continuous varispeed head, no grains). New parametersEngineModeParam,Position,Spray,Tiltextend the subclassParameterenum; subclasses must serve them fromget_parameter_*. Mode switches on a sounding voice fade through zero (k_mode_change_fade_duration).Sample mode in
MonoToStereoputs half the mono sum in each channel, the level a centred grain has under the linear pan law, so a mode switch no longer steps the level by 6 dB.Sample mode crossfades every head discontinuity — loop wrap, pitch-bank switch and retrigger — with a small pool of outgoing heads, so a second discontinuity inside a fade never hard-cuts.
Changed#
TANH_WITH_DOCSnow does something — it adds thesphinx-docstarget — and therefore defaults to OFF (it was ON and inert). A docs-enabled configure requires Doxygen and Python 3; consumers that already set it OFF are unaffected.dsp::granular::SamplePlayer: the equal-power crossfade reads a table instead of callingsin/cosper frame — a block fading the live head plus four outgoing tails wanted five transcendentals per frame. Becausecos(t * pi/2) == sin((1 - t) * pi/2), one quarter-sine table sized to the fade length inprepare()serves both directions, indexed straight by the integer fade counter: exact at every index, so the crossfade values are unchanged bit for bit.dsp::granular::GrainProcessorImpl: the voice gain pass skips the mode-fade ramp when the fade is already parked on its target, which is every block outside a mode switch. Same output, two fewer compares and a store per frame.dsp::granular::GrainEnginerender loop: bank pointers and pan gains are resolved once per block per grain, one channel-mode kernel is chosen per block, and the window comes from the newdsp::utils::MorphWindow. Roughly half the CPU at a full pool;test/dsp/benchmark_Granular.cppmeasures it. Idle voices no longer scan the pool and report to the visualiser every block.Position mode: a Spray window past either sample edge clips to the edge instead of wrapping to the other end — what the waveform band shows.
dsp::granularsplit into components:GrainProcessorImplis now the per-voice facade (parameter snapshotVoiceParams, master ADSR, mode fade) over a pre-allocatedGrainEngine(grain pool + scheduler, told where to start grains by aHeadPolicy:LoopScanHead/PositionSprayHead) and aSamplePlayer(the Sample-mode head).SampleReader,SampleRegionandchannel_mixerare the shared, header-only helpers. Constants and enums moved toGranularTypes.h(still reachable throughGrainProcessor.h). The subclass contract (Parameterenum, the threeget_parameter_*hooks) is unchanged. Behaviour differences: a Sustain change now retunes the decay slope at once (the per-setter path left the rate stale until another envelope parameter moved); lingering grains are always reported finished on reset / silence;prepare()starts the voice from silence.
Fixed#
thl::RCU: a version could be reclaimed while a reader was still inside the read scope that handed it out. A reader entering a section stores its generation and then loads the data pointer; the writer stores the pointer and then reads the generations. That store-load handshake needs sequential consistency, but usedmemory_order_release/acquire, which leave a release store free to sit in the core’s store buffer while the following load runs — so the writer could read generation 0 incleanup_safe_versions(), free the version, and leave the reader on freed memory. Seen as an intermittent audio-thread SIGSEGV on a freedProcessingConfiginConcurrentRebuild.RepeatedAddRemoveSingleRouting, reproducible only on some x86-64 hosts (Intel Xeon Platinum 8573C). The four handshake operations are nowmemory_order_seq_cst; the reader pays one locked exchange per section entry, still wait-free. Leaving a section is unchanged.dsp::granular::GrainProcessorImpl: volume modulation stepped the output.VoiceParams::m_volumeis a per-sub-block constant and was applied raw, so it was the only unsmoothed term in the voice gain (the ADSR already moves per sample) — a hard modulation step, such as a square LFO swinging both rails in one sample, reached the output as a discontinuity. The voice gain now ramps volume overk_volume_smoothing_duration(5 ms), seeded to the current level inprepare()and again at note-on so a voice starts at its level instead of sliding up to it.ModulationMatrix/RCU: data race between a schedule rebuild and the audio thread.RCU::updateis copy-on-write, so it deep-copies the live value — including eachResolvedRouting’sm_held_voice_valuesand per-voice freshness vectors, which the audio thread writes in place through the const routing it is processing.rebuild_schedule_with_lockassigns everyProcessingConfigmember anyway, so that copy was discarded immediately. NewRCU::replace()publishes a freshly built value without reading the one the readers hold; the rebuild now uses it.update()is unchanged and documents when not to use it. Caught by TSan viaConcurrentRebuild.PolyReplaceContentionChurnDoesNotCrash— the existing concurrency tests route Additive only and never touch the held state.ModulationMatrix: crash on the audio thread when a second Replace routing is added to a polyphonic target. A rebuild publishes each target’s freshVoiceBuffersone step before the newProcessingConfig, so an in-flight audio block still running the old routings can load a buffer whosem_has_replace_priorityhas just gone false -> true. That sends a routing resolved as single-Replace down the multi-Replace branch ofapply_replace_sample_voice, where it indexes per-voice freshness vectors its own rebuild left unsized – a null dereference on the audio thread. The vectors are now sized for every polyphonic Replace routing (contended or not), and the multi-Replace branch bounds-checks the voice index. Reproduced byConcurrentRebuild.PolyReplaceContentionChurnDoesNotCrash.
0.3.0 - 2026-09-03#
First release with a changelog: earlier releases (v0.1.0, v0.2.0) are described only by their tag messages (git tag -n1 v0.1.0 v0.2.0).
Added#
Logger: configurable platform-sink identity.LoggerConfig::m_platform_tag(Android logcat tag, journaldSYSLOG_IDENTIFIER),m_platform_subsystemandm_platform_category(Appleos_log) name what the platform sink files records under, so an embedder (anira) shows up under its own name inadb logcat -s, Console.app andlog stream. Defaults"thl","thl","logger"keep the previous output; an empty string selects the default. Set them before the first record: a laterset_config()applies to records dispatched after it returns, and on Apple platforms creates a newos_log_t(which the system never releases).Logger: per-record flags.LogRecord::m_flagstravels unchanged from the emitting site to the sinks (the console, file and platform sinks ignore it; the callback sink sees it). New overloads take the flags right after the level:log_with_source(level, flags, source, group, message),logf(level, flags, group, fmt, ...),rt::logf/rt::log(level, flags, ...)andrt::Queue::logf/vlogf/log(level, flags, ...); the existing signatures pass 0. Reserved bits:k_flag_realtime(1, set byrt::Queue::drain()on every record it dispatches) andk_flag_contract_violation(2, only ever set by the caller). The real-time producers stay allocation- and lock-free (one moreuint32_tin the fixed-size record).Logger:LogRecord::m_dropped_before. Art::Queue::drain()pass takes the queue’s drop counter before it pops and puts the count on the first record it dispatches; every other record carries 0, so summing the field over all records received counts every drop exactly once.format_plain()appends[N real-time log message(s) dropped before this record]andformat_logfmt()adropped_before=Nfield to a record that carries a count.CMake:
TANH_LOG_COMPILED_MAX_LEVEL(AUTO, or1..4) chooses the most verbose log level compiled into the call sites.AUTO, the default, keeps the historical rule (Error only in Release builds, every level otherwise); an embedder that wants its runtime level to be the only filter in a shipped build sets4as a plain variable before the fetch.
Changed#
Logger: the synthetic drop warning ofrt::Queue::drain()(level Warning, sourcert, groupthl.logger) is only dispatched when a pass has no record to carry the count. Its message is nowreal-time log queue overflowedwith the count inm_dropped_before(and in the rendered suffix), instead ofN real-time log message(s) dropped (queue full)after every pass with drops.