Have ideas to improve npm?Join in the discussion! »

    bergson

    0.14.1 • Public • Published

    Bergson

    What is Bergson?

    Bergson is the scheduling system for Flocking and Aconite. It provides a variety of clocks driven by different sources (such as requestAnimationFrame, the Web Audio API, and setInterval), and a priority queue-based scheduler that allows you to queue up one-time and repeating function calls.

    Bergson provides a very low-level API for scheduling, and is intended for library developers to build their own rhythmic and pattern-based abstractions on top of.

    Examples

    Creating a Scheduler with the requestAnimationFrame Clock

    var scheduler = berg.scheduler({
        components: {
            clock: {
                type: "berg.clock.requestAnimationFrame",
                options: {
                    freq: 60
                }
            }
        }
    });
    
    scheduler.start();
    

    Scheduling one-time events

    scheduler.schedule({
        type: "once",
        time: 30            // 30 seconds from now
        callback: function (now) {
            // Do something in the future.
        }
    });
    

    Scheduling repeating events

    scheduler.schedule({
        type: "repeat",
        time: 5,            // Start repeating five seconds from now.
        freq: 2,            // Repeat every two seconds.
        end: 20,            // Stop repeating 20 seconds from now.
        callback: function (now) {
            // Do something repeatedly.
        }
    });
    

    Listening for Clock Events Directly

    scheduler.clock.events.onTick.addListener(function (time, rate) {
        // Do something every time the clock ticks.
    });
    

    Bergson API

    Scheduler API

    Score Event Specifications

    A score event specification is a JSON-type (i.e. plain old, non-prototypal) object that describes the event to be scheduled. It can contain the following properties.

    Property Value Description
    type "once" or "repeat" The type of event to schedule (either one-time or repeating).
    time Number The future time in seconds when the scheduled event should occur.
    interval Number (Only for repeating events) The time interval, in seconds, between repetitions. This option takes precendence over freq if both are provided.
    freq Number (Only for repeating events) The frequency at which the event should repeat. This option will be overridden by interval if both are provided.
    end Number (Only for repeating events) The future time in seconds when the scheduled event should stop repeating.
    callback Function The function to invoke.

    Scheduler Model

    For more information on interacting with models, see the Infusion documentation about the Change Applier.

    Property Description Types
    timeScale The scheduler's time scale factor. Defaults to 1.0. Number

    Scheduler Members

    Property Description Types
    queue The priority queue used to sort and queue score events. berg.priorityQueue

    Scheduler Methods

    Method Description Argument Types Returns
    start Starts the scheduler and its clock. none undefined
    stop Stops the scheduler and its clock. none undefined
    schedule Schedules an event A _score event specification_ object The scheduled score event specification.
    clear Removes a scheduled event from the scheduler queue. The _score event specification_ to clear. undefined
    clearAll Removes all scheduled events from the scheduler queue. none undefined
    setTimeScale Sets the time scale factor for the scheduler. This will cause all time values for current and future scheduled events to be scaled by the specified value. Number undefined

    Clock API

    Clock Members

    Property Description Types
    time The current clock time, in seconds. Number
    freq The clock's frequency, in cyles per second. Number
    tickDuration The duration between ticks, in seconds. Number

    Clock Methods

    Method Description Argument Types Returns
    start Starts the clock. none undefined
    stop Stops clock. none undefined
    tick Advances the clock's time. (This will be invoked automatically for most clocks.) None undefined

    Clock Events

    Event Name Description Argument Types
    onTick Fires each time the clock ticks. Number time: the current clock time in seconds

    Types of Clocks

    Clock Description Default rate
    berg.clock.requestAnimationFrame A clock that is driven at (or as near as possible to) the display's refresh rate by the browser's built-in requestAnimationFrame function. Note that this clock will be throttled down to 1 Hz automatically by the browser if its tab is not active. 60 Hz. You must override this value if your display is running a different refresh rate.
    berg.clock.audioContext Uses the Web Audio API's AudioContext as a source of time. This clock needs to be driven by your own ScriptProcessorNode code (i.e. by calling its tick() method within your onaudioprocess handler). This clock will not start ticking until its start() method is invoked by a user action (such as a button click). Dynamically determined based on the AudioContext's sampleRate and this clock's blockSize option.
    berg.clock.autoAudioContext An AudioContext-based clock that will automatically create a ScriptProcessorNode instance and wire it up correctly for you. Use this if you're not using the Web Audio API directly, but want a rock-solid clock for scheduling events in your application. This clock will not start ticking until its start() method is invoked by a user action (such as a button click). Dynamically determined based on the AudioContext's sampleRate and this clock's blockSize option.
    berg.clock.setInterval A clock that is driven by the browser's built-in (and notoriously jittery) setInterval function. Use this if you don't need significant reliability, and want maximal cross-environment compatibility (e.g. with Node.js). Note that this clock will be throttled down automatically by the browser if its tab is not active. 10 Hz
    berg.clock.workerSetInterval Like berg.clock.setInterval, except that it employs a Web Worker in order to avoid the standard throttling done by browsers when the page is in the background. 10 Hz
    berg.clock.offline A base grade for creating your own types of clocks. An offline clock tracks time relatively (i.e. without reference to a "real" source of time such as the system clock). This clock should be driven manually by invoking its tick() method. 1 Hz
    berg.clock.realtime A base grade for creating your own types of clocks. A realtime clock tracks time based on the actual system time using, by default, performance.now(). This clock should be driven manually by invoking its tick() method. 1 Hz

    Building and Testing Bergson

    Prerequisites

    Bergson uses Node.js, npm, Grunt, and Testem for its build and test tooling. Here's how to get set up:

    1. Install the [Node.js](https://nodejs.org/en/) LTS release
    3. Install Grunt: <code>npm install -g grunt-cli</code>
    4. Install Testem: <code>npm install -g testem</code>
    

    How to Build Bergson

    To download all of Bergson's dependencies, build them, and then build Bergson itself, run the following commands:

    npm install
    grunt
    

    Running Bergson's Test Suite

    Bergson's test suite can be run on both Node.js and all of the browsers installed on your computer using Testem:

    npm test
    

    If you'd like to run only the Node.js tests, run:

    npm run node-test
    

    Or if you only want to run the browser tests:

    npm run browser-test
    

    Alternatively, if you'd like to only run the tests in one browser, you can open the test suite tests/unit/all-tests.html file by hand in your browser.

    Community

    Bergson is supported by the Flocking community and uses its forums:

    Mailing List

    The Flocking mailing list is the place to ask questions, share code, and request new features.

    Chat

    Flocking has an IRC channel, which can also be used to ask questions about Bergson. Join #flocking on irc.freenode.net.

    Credits and License

    Bergson is written and maintained by Colin Clark. It is dually licensed under the MIT and GPL 2.0 licenses.

    Install

    npm i bergson

    DownloadsWeekly Downloads

    28

    Version

    0.14.1

    License

    (MIT OR GPL-2.0)

    Unpacked Size

    1.63 MB

    Total Files

    59

    Last publish

    Collaborators

    • avatar