# offset
introduces structured timing deviations to incoming triggers: swing, jitter, or timing curves. transforms onset positions without altering their identity. operates atop both metrical (`grid`) and non-metrical (`field`) sources, with some forms only meaningful in grid contexts.

## families

* id 0 quantize

  * description: pull events toward nearest metrical point with adjustable strength
  * real-world analogy: timing correction or humanization
  * notes:

    * a controls snap strength (0 = no change, 1 = full quantize)
    * b controls curve sharpness (linear to exponential)
    * meaningful only when upstream is `grid` or metrical reference is available

* id 1 swing

  * description: delays every other subdivision to create rhythmic lilt
  * real-world analogy: shuffle feel, swing eighths
  * notes:

    * a sets swing ratio (0 = no swing, 1 = full delay)
    * b selects phase (0 = even beats delayed, 1 = odd)
    * assumes a uniform subdivision; applicable only with `grid`

* id 2 micro jitter

  * description: adds small random offsets to each event
  * real-world analogy: live performer timing variation
  * notes:

    * a sets max jitter range (fraction of segment)
    * b sets distribution shape (0 = uniform, 1 = gaussian)
    * applies to any trigger stream (grid or field)

* id 3 push/pull curve

  * description: applies a continuous timing bias curve over a segment
  * real-world analogy: expressive lean-in or drag
  * notes:

    * a controls curve direction (0 = push early, 1 = pull late)
    * b controls intensity
    * usable over both metrical and non-metrical streams

## parameter behaviour summary

* quantize

  * a: snap strength
  * b: snap curve sharpness
  * requires metrical reference

* swing

  * a: delay ratio
  * b: phase selector
  * requires regular subdivisions

* micro jitter

  * a: random offset range
  * b: distribution shape
  * works with any input

* push/pull curve

  * a: bias direction
  * b: bias intensity
  * works with any input

## why these were chosen

* quantize: precise or soft grid correction for `grid` inputs
* swing: idiomatic groove via asymmetric subdivision timing
* micro jitter: introduces subtle randomness with stable bounds
* push/pull curve: sculpts expressive arcs over time, agnostic to timing type

the set spans corrective, expressive, and stochastic timing deviations. two forms are general (`jitter`, `curve`), two require metrical context (`quantize`, `swing`).

## what’s not included

* per-event offset arrays (handled by `pattern`)
* tempo or meter warping (belongs to `structure`)
* feedback-based retiming or audio-reactive shifts (violates static determinism)
* multi-stream offset logic (handled via polymeter or inter-voice domains)

## conclusion

`offset` shapes micro-timing after trigger generation. its forms offer grid-bound correction, freeform deviation, and expressive shaping—completing the onset architecture’s timing layer. deterministic, local, and fully parametric, they remain valid across both `grid` and `field` foundations.