API reference by category

The complete public API, grouped by task. Click any function for its full signature, parameters, returns, and a link to the exact source line.

Core DSP & transforms

Function	Description
applyHannWindow	Apply a Hann window to an audio sample array.
blackman_window	Blackman window
buf_to_float	Convert an integer buffer to floating point values
computePeak	Find the peak absolute sample value across all channels of an audio buffer.
cqt	Constant-Q Transform of an audio signal.
createSpectrogram	Creates a spectrogram visualization of audio over time
debugLog	Log to the console only when debug logging is enabled.
f0_harmonics	Compute the energy at selected harmonics of a time-varying fundamental frequency
fft	Fast Fourier Transform using Cooley-Tukey algorithm (radix-2).
fft_frequencies	FFT frequencies
findDownbeatPhase	Find the true downbeat phase by analyzing onset patterns.
findKickSnareHit	Find kick+snare hit (strong transient with wide frequency content)
fix_frames	Fix a list of frames to lie within [x_min, x_max]
frame	Slice a data array into (overlapping) frames
get_window	Get window function
hamming_window	Hamming window
hann_window	Hann window
ifft	Inverse Fast Fourier Transform (complex input preserved, no component discarded).
isDebugEnabled	Report whether debug logging is currently enabled.
istft	Inverse Short-Time Fourier Transform
magnitude	Magnitude of complex spectrum
mel_to_stft	Approximate STFT magnitude from a Mel power spectrogram.
peakPick	Peak picking algorithm with advanced filtering
phase	Phase of complex spectrum
polar_to_complex	Convert magnitude and phase to complex spectrum
power	Power spectrum
rqa	Recurrence quantification analysis (RQA).
salience	Compute the harmonic salience function
setDebug	Enable or disable the library’s debug logging.
spectrogram	Simple spectrogram computation
stft	Short-Time Fourier Transform
sync	Aggregate a multi-dimensional array between boundaries, synchronizing features to a set of frames.
warnIfNoMp3Support	Check MP3 playback support and optionally show a warning banner.
yin	Fundamental frequency (F0) estimation using the YIN algorithm

Spectral features

Function	Description
computeRMS	Compute the Root Mean Square (RMS) energy of an audio buffer.
computeZeroCrossingRate	Compute the average zero-crossing rate across all channels of an audio buffer.
createRmsMeter	Create an incremental RMS meter.
delta_features	Compute delta (first-order derivative) features
feature.chroma_stft	Chromagram from a waveform or power spectrogram.
feature.dctBasis	Rows 0..n_out-1 of the DCT-II matrix over n_in points.
feature.estimate_tuning	Estimate tuning from a signal or spectrogram.
feature.foldLogSpectrumToChroma	Fold a time-major log-frequency spectrum into pitch classes by summing energy across octaves.
feature.logFrequencySpectrum	Log-frequency spectrum by nearest-FFT-bin sampling.
feature.melspectrogram	Mel spectrogram from a waveform with a (y, options) API.
feature.mfcc	Mel-frequency cepstral coefficients.
feature.mfccFromLogMel	MFCC cepstral core: DCT-II along the mel axis of a log-power mel spectrogram, keeping the first coefficients.
feature.piptrackPeaks	Pitch tracking on a thresholded, parabolically-interpolated STFT (piptrack); returns the sparse list of detected pitch/magnitude peaks.
feature.pitch_tuning	Tuning offset of a set of detected frequencies relative to A440, in fractions of a chroma bin.
feature.rms	Root-mean-square energy per frame (centered, constant-padded framing).
feature.spectral_bandwidth	p’th-order spectral bandwidth per frame.
feature.spectral_centroid	Spectral centroid (energy-weighted mean frequency) per frame.
feature.spectral_contrast	Spectral contrast: octave-band peak-to-valley energy difference per frame.
feature.spectral_flatness	Spectral flatness (geometric mean over arithmetic mean of the power spectrum) per frame.
feature.spectral_rolloff	Roll-off frequency: the lowest frequency bin whose cumulative energy reaches a given percentage of the total.
feature.zero_crossing_rate	Frame-wise zero-crossing rate with edge-padded centering.
findAllZeroCrossings	Collect the indices of every zero crossing in a signal.
findZeroCrossing	Find the next zero crossing at or after a given sample index.
mfcc_to_mel	Invert Mel-frequency cepstral coefficients to approximate a Mel power spectrogram

Beat & tempo

Function	Description
analyze_groove	Estimate groove and timing feel
beat_sync	Beat-synchronous feature aggregation
beat_track	Dynamic programming beat tracker.
beatTrack	Beat tracker with tempo estimation and dynamic-programming beat selection.
calculateBeatAlignment	Calculate how well a loop length aligns with musical timing
compute_tempogram	Compute tempogram using autocorrelation
detect_tempo_multiples	Detect tempo multiples and submultiples
detectBPM	Detect BPM from audio.
estimate_tempo	Estimate the global tempo (BPM) from a lag tempogram using tempo scoring.
extractTempo	Extract tempo from beat times Useful for validation and multiple tempo detection
fastBPMDetect	Fast BPM detection using onset detection plus tempo estimation.
find_tempo_candidates	Find tempo candidates from tempogram
findFirstDownbeat	Find the first strong downbeat in the track to help align loops to the musical phrasing.
fourier_tempogram	Fourier tempogram: the STFT of the onset strength envelope.
plp	Predominant Local Pulse (PLP) estimation
quickTempo	QUICK TIER — windowed live tempo estimate.
tempo	Estimate the global tempo (BPM) with aggregate=‘mean’.
tempoBasedCompress	Tempo-based audio compression — PITCH-PRESERVING time stretch via the phase vocoder.
tempogram	Local autocorrelation tempogram of the onset strength envelope.
tempogram_ratio	Tempogram ratio features (a.k.a. spectral rhythm patterns).

Tempo — BPM engine

Function	Description
bpm.analyzeTempogram	Analyze a tempogram to find its peak tempos.
bpm.analyzeWithProgress	Main analysis orchestrator that yields progress as it runs.
bpm.computeFourierTempogram	Compute a Fourier tempogram.
bpm.computeOnsetStrength	Compute onset strength using spectral flux.
bpm.computeSimpleFFT	Compute a simple FFT.
bpm.computeSimpleSpectrum	Compute a simple spectrum using a decimated FFT.
bpm.computeTempoFrequencies	Convert FFT bins to tempo frequencies.
bpm.estimateConstrainedTempo	Estimate tempo within a constrained range.
bpm.estimateGlobalTempo	Estimate global tempo using autocorrelation.

Onset detection

Function	Description
createFluxAnalyzer	Create an incremental spectral-flux analyzer.
onset_strength	onset_strength() — log-power-mel onset strength envelope.
onsetDetect	Fast spectral-flux onset detection — returns picked onset times directly.

Pitch & harmony

Function	Description
pitchBasedCompress	Pitch-based audio compression — a plain linear-interpolation resample kept at the original sample rate.
pyin	Probabilistic YIN (pYIN).

Loop detection

Function	Description
addLoopRegions	Adds loop region overlays to existing waveform
compareLoops	Quick loop comparison utility
createLoopBuffer	Create a loopable AudioBuffer with a custom waveform, multichannel support, and export options.
defineMultipleLoopPoints	Define multiple loop points for playback.
detectLoop	Detect loop points and return a real sample-range descriptor.
fastLoopAnalysis	Fast loop analysis — the default strategy of loop.detect().
findMusicalLoop	Simple loop finder that respects musical boundaries
fullBufferLoop	Return a loop spanning the entire buffer, performing no detection (the explicit whole-buffer descriptor used by resetLoop).
loop.analyzeLoopPoints	:::caution[Deprecated] Use loop.detect() instead. :::
loop.clamp01	Clamp a number into [0, 1]. NaN clamps to 0.
loop.detect	Detect loop points in an audio buffer.
loop.fastOnsetLoopAnalysis	:::caution[Deprecated] Use loop.detect(buffer, { strategy: ‘recurrence’ }) instead. :::
loop.findPreciseLoop	Find precise loop boundaries by testing actual audio repetition.
loop.loopAnalysis	:::caution[Deprecated] Use loop.detect() instead. :::
loop.measureLoopConfidence	Measure how well audio loops over [startSec, endSec), returning a confidence in [0, 1].
loop.musicalLoopAnalysis	Musical boundary-aware analysis.
loop.normalizedCrossCorrelation	Normalized cross-correlation (mean-subtracted, std-normalized) in [-1, 1].
loop.recurrenceLoop	Detect a loop via recurrence-matrix analysis.
loop.snapToZeroCrossings	Snap loop boundaries to nearby zero crossings to avoid clicks.
loop.xaLoopAnalysis	:::caution[Deprecated] Use loop.detect() instead. :::

Structural segmentation

Function	Description
segment.agglomerative	Bottom-up temporal segmentation: partition frames into k contiguous segments; returns the left-boundary frame indices.
segment.crossSimilarity	Cross-similarity between a comparison sequence and a reference sequence.
segment.lagToRecurrence	Convert a lag matrix back into a recurrence matrix.
segment.laplacianSegmentation	Structural segmentation of a beat/frame-synchronous feature matrix by Laplacian spectral clustering.
segment.recurrenceMatrix	Compute a recurrence (self-similarity) matrix from a feature matrix.
segment.recurrenceToLag	Convert a recurrence matrix into a lag matrix.

Recurrence

Function	Description
recurrence.computeChroma	Compute chroma features from audio buffer
recurrence.findLoopCandidates	Find peaks in lag matrix to identify loop-lag candidates.
recurrence.framesToTime	Convert frames to time (xa-style)
recurrence.recurrenceLoopDetection	Recurrence loop detection using matrix analysis.
recurrence.recurrenceMatrix	Proper recurrence matrix (xa-style)
recurrence.recurrenceToLag	Convert a recurrence matrix to its lag representation (xa-style).
recurrence.stackMemory	Time-delay embedding to stack chroma features.

Sequence alignment (DTW · Viterbi · RQA)

Function	Description
sequence.dtw	Dynamic time warping between two feature sequences (or a precomputed cost matrix).
sequence.dtwBacktracking	Backtrack a warping path from a recorded step matrix.
sequence.matchEvents	Match one set of events to another (nearest neighbor with optional left/right constraints).
sequence.matchIntervals	Match one set of time intervals to another, maximizing Jaccard similarity.
sequence.transition_cycle	Construct a cyclic transition matrix.
sequence.transition_local	Construct a localized transition matrix where each state transitions only to nearby states.
sequence.transition_loop	Construct a self-loop transition matrix.
sequence.transition_uniform	Construct a uniform transition matrix over nStates.
sequence.viterbi	Viterbi decoding from observation likelihoods.
sequence.viterbi_discriminative	Viterbi decoding from discriminative (mutually exclusive) state posteriors.

Decomposition & separation

Function	Description
decompose.hpss	Median-filtering harmonic/percussive source separation on a spectrogram.
decompose.nn_filter	Nearest-neighbor filtering (nn_filter).
decompose.optimizeEqCurves	Optimize EQ curves to match mixture fingerprints to vocal fingerprints
decompose.processAudioToFingerprints	Process audio to create complete fingerprint
decompose.reconstructVocal	Reconstruct vocal audio using learned EQ curves
decompose.softmask	Robust soft mask M = X^power / (X^power + X_ref^power), computed with a rescale-by-max stabilization.
griffinlim	Griffin-Lim algorithm for phase reconstruction
pcen	Per-Channel Energy Normalization (PCEN)

Effects

Function	Description
effects.deemphasis	De-emphasis filter — the exact inverse of preemphasis().
effects.harmonic	Extract only the harmonic component of a waveform.
effects.hpss	Decompose an audio time series into harmonic and percussive components.
effects.percussive	Extract only the percussive component of a waveform.
effects.phase_vocoder	Phase vocoder: time-stretch an STFT matrix by a given rate.
effects.pitch_shift	Shift the pitch of a waveform by n_steps steps while preserving duration.
effects.preemphasis	Pre-emphasis filter that boosts high frequencies (the inverse of deemphasis()).
effects.remix	Remix an audio signal by re-ordering time intervals.
effects.split	Split an audio signal into non-silent intervals.
effects.time_stretch	Time-stretch an audio series by a fixed rate while preserving pitch.
effects.trim	Trim leading and trailing silence from an audio signal.

Filter banks

Function	Description
filters.chroma	Chroma filter bank. Projects FFT bins onto n_chroma pitch classes via Gaussian bumps.
filters.mel_filterbank	Create Mel filterbank matrix

Unit conversions

Function	Description
convert.A4_to_tuning	Convert reference pitch A4 frequency to tuning deviation
convert.a_weighting	A-weighting of frequency
convert.amplitude_to_db	Convert amplitude to decibels
convert.b_weighting	B-weighting of frequency
convert.blocks_to_frames	Convert block indices to frame indices
convert.blocks_to_samples	Convert block indices to sample indices
convert.blocks_to_time	Convert block indices to time (in seconds)
convert.c_weighting	C-weighting of frequency
convert.cqt_frequencies	Compute CQT (Constant-Q Transform) frequencies
convert.d_weighting	D-weighting of frequency
convert.db_to_amplitude	Convert decibels to amplitude
convert.db_to_power	Convert decibels to power
convert.fft_frequencies	Compute FFT frequencies
convert.fourier_tempo_frequencies	Compute Fourier tempogram frequencies
convert.frames_to_samples	Convert frame indices to sample indices
convert.frames_to_time	Convert frame indices to time (seconds)
convert.frequency_weighting	General frequency weighting function (wrapper for A/B/C/D/Z weightings)
convert.hz_to_mel	Convert Hz to Mel scale
convert.hz_to_midi	Convert Hz to MIDI note number
convert.hz_to_note	Convert Hz to note name
convert.hz_to_octs	Convert Hz to octaves (relative to C0)
convert.lag_to_tempo	Convert lag (in frames) to BPM
convert.mel_frequencies	Compute the mel-scale frequencies
convert.mel_to_hz	Convert Mel scale to Hz
convert.midi_to_hz	Convert MIDI note number to Hz
convert.midi_to_note	Convert MIDI note number to note name
convert.multi_frequency_weighting	Compute multiple frequency weightings at once
convert.note_to_hz	Convert note name to Hz
convert.note_to_midi	Convert note name to MIDI note number
convert.octs_to_hz	Convert octaves to Hz
convert.perceptual_weighting	Perceptual weighting curve (approximate)
convert.power_to_db	Convert power to decibels
convert.samples_like	Return an array of sample indices to match the time axis from a feature matrix
convert.samples_to_frames	Convert audio samples to frame indices
convert.samples_to_time	Convert sample indices to time (seconds)
convert.tempo_frequencies	Compute the tempo frequencies (in BPM) corresponding to lag-tempogram bins.
convert.tempo_to_lag	Convert BPM to lag (in frames)
convert.time_to_frames	Convert time (seconds) to frame indices
convert.time_to_samples	Convert time (seconds) to sample indices
convert.times_like	Return an array of time values to match the time axis from a feature matrix
convert.tuning_to_A4	Convert tuning deviation to A4 reference frequency
convert.z_weighting	Z-weighting (flat/no weighting) for frequency analysis

Music notation

Function	Description
notation.fifths_to_note	Calculate the note name for a given number of perfect fifths
notation.hz_to_fjs	Convert one or more frequencies (in Hz) to Functional Just System (FJS) notation
notation.hz_to_svara_c	Convert frequencies (in Hz) to Carnatic svara notation within a melakarta raga
notation.hz_to_svara_h	Convert frequencies (in Hz) to Hindustani svara notation
notation.interval_to_fjs	Convert an interval to Functional Just System (FJS) notation
notation.key_to_degrees	Construct the diatonic scale degrees for a given key
notation.key_to_notes	List all 12 chromatic note names as spelled according to a given key.
notation.list_mela	List melakarta ragas by name and index
notation.list_thaat	List supported thaats by name
notation.mela_to_degrees	Construct the svara indices (degrees) for a given melakarta raga
notation.mela_to_svara	Spell the Carnatic svara names for a given melakarta raga
notation.midi_to_svara_c	Convert MIDI numbers to Carnatic svara within a melakarta raga
notation.midi_to_svara_h	Convert MIDI numbers to Hindustani svara
notation.note_to_svara_c	Convert western note names to Carnatic svara within a melakarta raga
notation.note_to_svara_h	Convert western note names to Hindustani svara
notation.thaat_to_degrees	Construct the svara indices (degrees) for a given thaat

Intervals

Function	Description
intervals.compareTuningSystems	Compare different tuning systems
intervals.generateFrequencies	Quick frequency generation utility
intervals.interval_frequencies	Construct interval frequencies (convenience wrapper)
intervals.plimit_intervals	Construct p-limit intervals (convenience wrapper)
intervals.pythagorean_intervals	Construct Pythagorean intervals (convenience wrapper)

Linear algebra

Function	Description
linalg.eigh	Symmetric eigendecomposition via cyclic Jacobi rotations.
linalg.laplacian	Normalized graph Laplacian of a dense weight matrix.

Clustering

Function	Description
cluster.kmeans	K-means clustering — Lloyd’s algorithm with greedy k-means++ seeding.

Display & visualization

Function	Description
analyzeWaveform	Calculates waveform statistics for analysis
cmap	Get a default colormap from the given data
createInteractiveRenderer	Creates an interactive waveform renderer with events
drawWaveform	Draw waveform visualization
getStereoWaveformPeaks	Extracts stereo waveform data for left and right channels
getTimebasedWaveform	Generates time-based waveform data with precise time stamps
getWaveformPeaks	Extracts waveform peaks suitable for visualization
getWaveformRange	Generates waveform data for a specific time range
harmonic_product_spectrum	Compute harmonic product spectrum (HPS) for pitch detection
renderStaticSpectrum	Renders static spectrum analysis of audio buffer
renderStereoWaveform	Renders stereo waveform with separate channels
renderWaveform	Renders waveform data to a canvas element
specshow	Display a spectrogram/chromagram/CQT/etc on a Canvas element
waveshow	Visualize a waveform in the time domain on a Canvas element

Audio I/O — synthesis & codecs

Function	Description
audioio.autocorrelate	Autocorrelation of a signal up to a maximum lag.
audioio.chirp	Synthesize a linear or exponential frequency sweep (chirp).
audioio.clicks	Synthesize a click track at the given times or frames.
audioio.getDuration	Compute a signal’s duration in seconds from its length and sample rate.
audioio.getSamplerate	Read the sample rate of an AudioBuffer.
audioio.load	Fetch and decode an audio file, with optional mono downmix, resampling, offset, and duration.
audioio.lpc	Burg LPC (real‑valued) — returns LPC denominator polynomial a[0..p], a[0] == 1
audioio.muCompress	mu-law compress a signal, optionally quantizing to integer codewords.
audioio.muExpand	mu-law expand (decode) a companded signal back to linear amplitude.
audioio.play	Play the currently loaded audio through the Web Audio API, optionally looping.
audioio.resample	Linearly resample a signal from one sample rate to another.
audioio.stop	Stop the current Web Audio playback and release the source node.
audioio.toMono	Downmix multi-channel audio to a single mono channel by averaging.
audioio.tone	Synthesize a pure sinusoidal tone at a given frequency.
audioio.zeroCrossings	Mark the sample positions where the signal changes sign.

Audio I/O — files & cache

Function	Description
file.cache	Get cache management interface
file.createAudioContext	Create a new Web Audio API context with proper configuration
file.createVisualization	Create audio visualization data
file.example	Load example audio file from remote source
file.exampleAudio	Get audio data as Float32Array from AudioBuffer
file.exampleBuffer	Load and decode audio example to AudioBuffer
file.exampleInfo	Get metadata for a specific example
file.isWebAudioSupported	Utility function to check if Web Audio API is available
file.listExamples	List all available audio examples
file.saveAudio	Save audio data as downloadable file

Audio I/O — streaming

Function	Description
fileio.cite	Get citation information for the pleco-xa library
fileio.createMediaStreamProcessor	Create a real-time audio stream processor for live input
fileio.find_files	Get a sorted list of audio files using File System Access API
fileio.stream	Chunked audio reader (NOT true streaming — honesty note, 2026-07-02).

Audio I/O & playback

Function	Description
applyLiveDoubleSpeed	Raise live playback to double speed in real time (crossfaded playback rate, or pitch-preserving resample).
applyLiveHalfSpeed	Drop live playback to half speed in real time (crossfaded playback rate, or pitch-preserving resample).
createAudioBlob	Encode an AudioBuffer’s first channel as a WAV Blob.
decodeWav	Decode a WAV file into planar Float32Array channels (PCM 16/24/32-bit integer and 32-bit float).
encodeWav	Encode planar channel data as an interleaved 16-bit PCM WAV file.
exportBufferAsWav	Export an AudioBuffer as a .wav file.
findAudioStart	Find where audible audio begins (first sample above a threshold, snapped to the nearest zero crossing).
initAudioProcessor	Initialize the audio processor
loadAudioFile	Load audio file (from URL or File object)
loadFile	Load local audio file from user input
mel_to_audio	Invert a mel power spectrogram to audio using Griffin-Lim
mfcc_to_audio	Convert Mel-frequency cepstral coefficients to a time-domain audio signal
resetLiveSpeed	Reset live playback back to normal (1x) speed.
valid_audio	Determine whether a variable contains valid audio data

Playback

Function	Description
playback.closeGapLeft	Close a detected gap by shifting the audio after it left. The normalized loop end is preserved.
playback.closeGapRight	Close a detected gap by removing it and rescaling the loop end to the shorter buffer.
playback.createBufferLike	Default pure buffer factory: an AudioBuffer-shaped object backed by Float32Array channels.
playback.detectGap	Detect a gap (silence across all channels) after the loop end.
playback.doubleSpeedQuantzLoop	Double speed quantz — gapless: compress the loop content at 2x speed into half the space and re-fill.
playback.doubleSpeedUnquantzLoop	Double speed unquantz: compress the loop content at 2x speed in place (track length unchanged).
playback.halfSpeedLoop	Half speed (time stretch) a loop section. The loop region is stretched to 2x its length.
playback.halfSpeedQuantzLoop	Half speed quantz: time-stretch the loop content at half speed but mask it to the original length.
playback.revealFirstHalf	Reveal the first half of a half-speed-quantz’d loop (counterpart of revealHiddenHalf; toggles back).
playback.revealHiddenHalf	Reveal the “hidden” second half of a half-speed-quantz’d loop by replacing the loop window with it.
playback.reverseSection	Reverse a sample range of a buffer without mutating the input (copy-then-reverse).

Experimental & creative play

The Echoplex-inspired live-performance and glitch layer — the creative-play tier, not part of the stable analysis API. These helpers mutate loops and buffers in place for real-time performance and algorithmic sequencing; treat their signatures and behavior as experimental.

Function	Description
applyOperationEnhanced	Apply a loop operation with live responsiveness — large reverse operations run in chunks with progress callbacks.
applyQuantumOp	Apply a single named operation (half, double, move, reverse, reset, stutter, phase, fractal) to a buffer and loop.
buildQuantumOpList	Build an operation list by warping a random seed through vector space and injecting preset accent bars.
buildQuantumSequence	Turn an operation list into a list of executable playback steps, each applying one operation to the buffer and loop.
checkBufferSafety	Validate a buffer and loop range, reporting whether the operation is safe along with any issues and loop metrics.
doubleLoop	Double a loop descriptor’s length by extending its end, clamped to the buffer length.
executeOperation	Apply a single named loop operation (half, double, move, reverse, reset, stutter, fractal, phase) to a buffer and loop.
generateChaotic	Generate a chaotic sequence of loop operations driven by a logistic-map iterator.
generateFibonacci	Generate a Fibonacci-patterned sequence of loop operations.
generatePrimeRhythm	Generate a prime-number-driven rhythmic sequence of loop operations.
generateWaveform	Generate a sine-wave-modulated sequence of loop operations.
glitchBurst	Run a time-boxed burst of randomized loop glitches on an internal clock; returns a stop function.
halfLoop	Halve a loop descriptor, keeping the start and moving the end to the midpoint.
isLargeOperation	Decide whether a loop operation counts as large (long loop, high buffer share, or long file) and warrants chunked processing.
moveForward	Advance a loop descriptor forward by a number of samples, clamped so it never runs past the buffer end.
playQuantumOps	Play a quantum operation sequence with adaptive, oscillating per-operation timing.
randomLocal	Apply a short random burst of loop operations to the current loop and return the result.
randomPreset	Return a randomly chosen preset beat pattern (an eight-step operation bar) for injection into a sequence.
randomSequence	Build a randomized sequence of loop-manipulation steps (move, half, double, reverse, reset) for live playback.
resetLoop	Reset a loop descriptor to span the entire buffer.
reverseBufferSection	Reverse a sample range of a buffer in place (mutates the buffer).
signatureDemo	Build the library’s fixed signature demo — narrow, move, reverse, grow, and finish — as a list of playable steps.
startBeatGlitch	Start a beat-synchronized glitch that fires random loop operations once per detected bar; returns a stop function.