Purpose

• Help an application developer and their coding agent integrate and use @kzkymur/sequencer effectively.

• Provide minimal, reliable steps with links to focused references.

When To Use

• Building animations, audio cues, game or UI events, or any timed workflow.

• Needing linear (serial) or overlapping (parallel) event execution with millisecond control.

Quick Workflow

• Choose Mode

• Queue (class Sequencer ): run fragments strictly in order.

• Independent (class IndependentSequencer ): run fragments by start time; multiple can overlap.

• Define Fragments

• Queue: new Fragment(name, durationMs, callback?) .

• Independent: new IndependentFragment(name, durationMs, startMs, callback?) .

• Modular: new CustomFragment(name, startMs) then addFragment(...) with independent/custom fragments; duration is computed; callback cannot be set directly.

• Initialize

• Queue: const seq = new Sequencer(pitchMs, speed=1.0, loop=false, useUniversalWorker=false) .

• Independent: const seq = new IndependentSequencer(pitchMs, speed=1.0, loop=false) .

• Pitch is the tick interval; smaller is smoother but costlier. useUniversalWorker=true improves timer precision.

• Compose

• push(fragment) to append.

• insert(index, fragment) for Queue only (throws on Independent).

• remove(fragment) by identity.

• Control

• await seq.play(delayMs=0) ; throws if already playing or delay < 0.

• seq.stop(delayMs=0) ; throws if not playing or delay < 0.

• await seq.waitCompleted() to await natural end (must be playing).

• await seq.replay(delayMs=0) ; requires not playing; resets time to 0.

• Visualize (optional)

• seq.renderToCanvas(ctx, { width?, height?, activeColor?, inactiveColor?, timeIndicatorColor? }) .

Safety & Error Guards (agent-minded)

• Validate inputs before calling:

• setPitch(p > 0) , setSpeed(s > 0) ; non-positive or NaN throws.

• play/stop(delay >= 0) ; negative or NaN throws.

• insert(0..fragments.length) ; out-of-range throws.

• Duplicates: pushing a fragment with an existing id throws.

• Independent mode: insert(...) always throws (unsupported).

• CustomFragment: cannot set callback; name must be non-empty; start must be ≥ 0.

Handy Getters

• getFragments() returns a copy of current fragments.

• getCurrentTime() current elapsed ms.

• getPitch() , setPitch(...) .

• setSpeed(...) , setLoopFlag(...) , isLooping() .

Open These References When Needed

• references/quick-start.md – install + minimal setup.

• references/api.md – precise method signatures and invariants.

• references/patterns.md – common patterns (UI, audio, games, tasks).

• references/testing.md – unit/integration test scaffolds.

• references/troubleshooting.md – known errors and fixes.

Notes For Coding Agents

• Prefer creating fragments once and reusing via .copy() when repeating patterns.

• Await waitCompleted() when callers expect completion before proceeding.

• For canvas, ensure totalDuration > 0 before rendering to avoid divide-by-zero visuals.

• For high precision timelines, set useUniversalWorker=true (Queue mode) and avoid heavy work in callbacks.

References

• See the skill-creator guidance in .agents/skills/skill-creator/ for structure and progressive disclosure patterns.