{"id":13768326,"url":"https://github.com/colinbdclark/Flocking","last_synced_at":"2025-05-10T23:31:15.987Z","repository":{"id":58221054,"uuid":"271097413","full_name":"colinbdclark/Flocking","owner":"colinbdclark","description":"Flocking - Creative audio synthesis for the Web","archived":false,"fork":true,"pushed_at":"2024-07-10T22:05:50.000Z","size":55874,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-14T23:29:41.435Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"lichen-community-systems/Flocking","license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/colinbdclark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-06-09T19:59:16.000Z","updated_at":"2024-09-16T03:23:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/colinbdclark/Flocking","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colinbdclark%2FFlocking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colinbdclark%2FFlocking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colinbdclark%2FFlocking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colinbdclark%2FFlocking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/colinbdclark","download_url":"https://codeload.github.com/colinbdclark/Flocking/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253497296,"owners_count":21917683,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T16:01:19.742Z","updated_at":"2025-05-10T23:31:10.974Z","avatar_url":"https://github.com/colinbdclark.png","language":"JavaScript","readme":"Flocking - Creative audio synthesis for the Web!\n================================================\n\nWhat is Flocking?\n-----------------\n\nFlocking is a JavaScript audio synthesis framework designed for artists and musicians\nwho are building creative and experimental Web-based sound projects.\nIt supports Firefox, Chrome, Safari on\nMac OS X, Windows, Linux, iOS, and Android.\n\nUnlike comparable tools, Flocking is declarative. Its goal is to promote a uniquely\ncommunity-minded approach to instrument design and composition.\nIn Flocking, unit generators and synths are specified as JSON,\nmaking it easy to save, share, and manipulate your synthesis algorithms.\nSend your synths via Ajax, save them for later using HTML5 local data storage,\nor algorithmically produce new instruments on the fly.\n\nBecause it's just JSON, every instrument you build using Flocking can be easily modified\nand extended by others without forcing them to fork or cut and paste your code.\nThis declarative approach will also help make it easier to create new authoring,\nperformance, metaprogramming, and social tools on top of Flocking.\n\nFlocking was inspired by the [SuperCollider](https://supercollider.github.io/)\ndesktop synthesis environment. If you're familiar with SuperCollider,\nyou'll feel at home with Flocking.\n\nTo learn more about Flocking's architecture and approach, please see:\n\nClark, C. and Tindale, Adam. \"[Flocking: A Framework for Declarative Music-Making on the Web](https://github.com/colinbdclark/flocking-papers/blob/master/icmc-2014/flockingicmc2014.pdf?raw=true)\"\nin Georgaki, A. and Kouroupetroglou (eds.). _The Joint Proceedings of the ICMC and SMC_, (2014).\n_[slides](colinclark.org/presentations/flocking-icmc-2014-slides.pdf)_\n\nFlocking does not currently support the Web Audio API's new [AudioWorklet](https://www.w3.org/TR/webaudio/#audioworklet) specification, which allows for JavaScript-based signal processing code to run in a separate, real-time thread. This means that Flocking is not currently well-suited to applications that involve a lot of graphics rendering or user interaction. Work is underway on a new core for Flocking, called [Signaletic](https://github.com/colinbdclark/signaletic/tree/gh-1), which will provide full support for all Web Audio native nodes as well as the use of AudioWorklets.\n\nCommunity\n---------\n\nFlocking has an inclusive and supportive community with several forums where you can ask for help\nand share the projects you're working on.\n\n### Mailing List\nThe [flocking mailing list](https://lists.idrc.ocadu.ca/mailman/listinfo/flocking)\nis the place to ask questions, share code, and request new features.\n\n### Chat\nFlocking has an IRC channel. Join \u003ccode\u003e#flocking\u003c/code\u003e on \u003ccode\u003eirc.freenode.net\u003c/code\u003e.\n\n\nStatus and Roadmap\n------------------\n\nFlocking is in active development. It has bugs and it is growing quickly.\n\nThe project's [development roadmap](https://github.com/continuing-creativity/Flocking/wiki/Release-Plan)\nis documented in the wiki. Plans include:\n * Better support for interleaving Flocking unit generators with Web Audio API nodes\n * A new format for specifying connections between unit generators\n * A \"live data merging\" environment for live coding\n * Graphical editing of Flocking synth defs\n\nUnplanned features, bug fixes, and contributions are welcome and appreciated, of course. The Flocking project adheres to the [Contributor Covenant guidelines](https://contributor-covenant.org/version/1/2/0/), and is an open and welcoming community.\n\n\nDocumentation and Demos\n-----------------------\n\n* Flocking's [documentation](docs/) is in the repository\n* Demos can be found in the [Flocking Playground](https://flockingjs.org/demos/playground)\n* Other examples are located in the [examples repository](https://github.com/colinbdclark/flocking-examples)\n\n\nGetting Started\n---------------\n\nThe latest stable release of Flocking can be downloaded from the [Flocking releases](https://github.com/continuing-creativity/Flocking/releases) page.\n\nConcatenated and minified Flocking builds, suitable for development and production respectively,\nare included in the [dist directory](dist/). Flocking can also be built manually using Grunt.\n\nHere's how to include Flocking's development file in your HTML page:\n\n    \u003c!-- This includes Flocking and all its dependencies, including jQuery and Infusion --\u003e\n    \u003cscript src=\"flocking/dist/flocking-all.js\"\u003e\u003c/script\u003e\n\n\nFor more information on using Flocking in a browser,\nread the [Getting Started](docs/getting-started.md) tutorial.\nIf module loaders are your thing, Flocking also supports the CommonJS and AMD styles.\n\n\nUsing Flocking\n--------------\n\nFlocking consists of a handful of primary components that are configured using JSON\nspecifications. These include: Unit Generators (ugens), Synths, Schedulers, and the Environment.\n\n### Unit Generators ##\n\nUnit generators, or _ugens_ for short, are the basic building blocks of synthesis;\nthey do the work of generating or processing audio signals in Flocking.\nUGens have multiple inputs and a single output. Some unit generators support\nmultiple input or output multiple channels.\n\nA unit generator can be wired to other unit generators,\nsupporting sophisticated signal processing graphs.\nUnit generators implement one primary method, \u003ccode\u003egen(numSamps)\u003c/code\u003e,\nwhich is responsible for processing a block of audio samples.\n\nTypically, however, you never need to interact with unit generator instances directly.\nInstead, you create declarative \"unit generator definitions\" (_ugenDefs_) objects,\nletting Flocking take care of creating the actual unit generator instances.\nUGenDefs are composed into trees called _synthDefs_.\nHere's an example of a ugenDef:\n\n    {\n        id: \"carrier\",             // A unique ID used when updating this ugen's input values.\n\n        ugen: \"flock.ugen.sinOsc\", // The fully-qualified name of the desired unit generator,\n                                   // specified as a \"key path\" (a dot-separated string).\n\n        rate: \"audio\",             // The rate at which the unit generator should run.\n\n        inputs: {                  // The input values for this unit generator. Each UGen has different inputs.\n            freq: 440              // For convenience, these inputs don't need to be nested inside the \"inputs\"\n        },                         // container, but you might want to for readability.\n\n        options: {\n            interpolation: \"linear\" // Other non-signal options such as interpolation rates, etc.\n                                    // Options are also specific to the type of unit generator.\n        }\n    }\n\n### Synths ###\n\nA Synth is a self-contained collection of unit generators that represents a\nsynthesizer, instrument, or signal processor of some kind.\nMultiple synths can run at the same time, and they can be connected together\nusing shared interconnect buses.\nFor example, a mixing board Synth could be created to mix and process signals from\nseveral tone-generating Synths and effect Synths.\n\nTo create a synth, you specify a \u003ccode\u003esynthDef\u003c/code\u003e option, which is a declarative\ntree of unit generator definitions. Here's a simple example of a sine oscillator (named _carrier_)\nwhose amplitude is modulate by another sine oscillator, _mod_:\n\n    {\n        id: \"carrier\",                  // Name this unit generator \"carrier,\" exposing it as an input to the synth.\n        ugen: \"flock.ugen.sinOsc\",      // Sine oscillator ugen.\n        freq: 440,                      // Give it a frequency of 440 Hz, or the A above middle C.\n        mul: {                          // Modulate the amplitude of this ugen with another ugen.\n            id: \"mod\",                      // Name this one \"mod\"\n            ugen: \"flock.ugen.sinOsc\",      // Also of type Sine Oscillator\n            freq: 1.0                       // Give it a frequency of 1 Hz, or one wobble per second.\n        }\n    }\n\nSynths can be updated in realtime by using the \u003ccode\u003eget()\u003c/code\u003e and \u003ccode\u003eset()\u003c/code\u003e methods.\nAny unit generator with an \u003ccode\u003eid\u003c/code\u003e property in its ugenDef will automatically be\nexposed as a named input to the synth. To update a unit generator, a _key path_ is used to specify\nthe desired input. Key paths are dot-delimited, path-like strings that allow you to address any part of the\nunit generator tree. Here's an example of a key path:\n\n    \"carrier.freq.mul\" // Refers to the amplitude (mul) of the carrier's frequency.\n\n#### Getting Synth Inputs ####\n\nAn input can be retrieved from a synth by invoking the \u003ccode\u003eget()\u003c/code\u003e method with a key path.\nIf the target of the path is a _value unit generator_, its value will be returned directly.\nIf it is any other kind of input, its ugen instance will be returned instead.\n\n    var freq = synth.get(\"carrier.freq\");\n\n#### Setting Synth Inputs ###\n\nSynth inputs can be set by calling the aptly-named \u003ccode\u003eset()\u003c/code\u003e method.\nFlocking's signal processing pipeline is dynamic, so unit generators can be added\nor replaced at any time. Behind the scenes, everything is a unit generator,\neven static values.\n\nUpdating a value:\n\n    synth.set(\"carrier.freq\", 440);\n\nReplacing the target unit generator with a new one:\n\n    synth.set(\"carrier.freq\", {\n        ugen: \"flock.ugen.sinOsc\",\n        freq: 2\n    });\n\nUpdating multiple inputs at once:\n\n    synth.set({\n        \"carrier.freq\": 440,\n        \"carrier.mul\": 0.5,\n        \"modulator.freq\": 123\n    });\n\n\n### Rates ###\n\nTo ensure reasonable performance on resource-constrained devices such as phones and low-power computers\n(e.g. Chromebooks, Raspberry Pi), Flocking uses a block-based architecture. By default, ugens and synths will\nproduce 64 samples per block. This value is configurable by specifying the \u003ccode\u003eblockSize\u003c/code\u003e\noption when initializing Flocking.\n\nThere are three primary types of signal rates in Flocking: \u003ccode\u003eaudio\u003c/code\u003e, \u003ccode\u003econtrol\u003c/code\u003e,\nand \u003ccode\u003econstant\u003c/code\u003e. Audio rate produces a full block of samples,\ncontrol rate produces one sample per block, and constant rate will alway produce the same value.\nSynths also support two other rates, \u003ccode\u003edemand\u003c/code\u003e and \u003ccode\u003escheduled\u003c/code\u003e. A demand rate synth\nwill only produce a value when its \u003ccode\u003egen()\u003c/code\u003e method is invoked. Scheduled synths are under the\ncontrol of a scheduler instead of the sample output clock.\n\n\n### The Environment ##\n\nAn Environment represents a whole \"audio system\" or \"context\" in Flocking.\nIt is responsible for evaluating all Synths instances and outputting their samples to the\ncurrent audio output strategy. An environment manages a list of Synth instances and evaluates them in order.\nYou should instantiate only one \u003ccode\u003eflock.enviro\u003c/code\u003e for your entire application.\n\nThe Flocking _shared environment_ is created by calling \u003ccode\u003eflock.init()\u003c/code\u003e:\n\n    var environment = flock.init();\n\nBefore you'll hear any sound, the environment needs to be started. You only need to start the environment once.\nThis is done using the \u003ccode\u003estart()\u003c/code\u003e method:\n\n    environment.start();\n\nTo stop the environment from generating samples, use the \u003ccode\u003estop()\u003c/code\u003e method:\n\n    environment.stop();\n\n#### Synths and the Environment ####\n\nBy default, synths are automatically added to the end (or _tail_) of the environment's list of synths.\nThis means that synths will start playing immediately when you create them.\n\nIf you want to defer the playing of a Synth to a later time,\nyou can override the \u003ccode\u003eaddToEnvironment\u003c/code\u003e option when you instantiate it:\n\n    var mySynth = flock.synth({\n        synthDef: {\n            ugen: \"flock.ugen.sin\",\n            freq: 440\n        },\n        addToEnvironment: false\n    });\n\nIf you need to manage the Environment's list of synths manually,\nyou can use the methods provided by the flock.nodeListComponent _grade_.\n\nTo add a synth to the head of the graph so that it will be evaluated first:\n\n    enviro.head(mySynth);\n\nTo add a synth to the tail of the graph so that it will be evaluated after all other synths):\n\n    enviro.tail(mySynth);\n\n### Schedulers ###\n\nA scheduler allows you to schedule changes to Synths at a particular time.\nCurrently, there is one type of Scheduler, the asynchronous scheduler.\nUnfortunately, it is driven by the browser's notoriously inaccurate setTimeout() and setInterval() clocks,\nwhich means that it will drift by up to 75 ms depending on the browser's load.\nIn practice, however, this drift is sufficient for scheduling many kinds of changes,\nand if sample-level accuracy is needed, unit generators such as \u003ccode\u003eflock.ugen.sequence\u003c/code\u003e,\n\u003ccode\u003eflock.ugen.change\u003c/code\u003e and  \u003ccode\u003eflock.ugen.random\u003c/code\u003e can be used.\n\nA block-accurate scheduler is planned for an upcoming release of Flocking.\nIn the meantime the asynchronous scheduler does a decent job of keeping \"pleasantly inaccurate\" time.\n\nIf you need to, you can always schedule arbitrary events using plain old functions:\n\n    // Fade out after 8 seconds.\n    band.scheduler.once(8, function () {\n        band.sinSynth.set({\n            \"carrier.mul.start\": 0.25,\n            \"carrier.mul.end\": 0.0,\n            \"carrier.mul.duration\": 1.0\n        });\n    });\n\nThe Flocking scheduler, in future releases, will be removed and replaced with [Bergson](https://github.com/colinbdclark/bergson), a highly accurate scheduler written specifically for audio and video applications.\n\n\nTesting\n-------\n\nFlocking uses Testem and Vagrant to run its test suite across many of its supported environments, both on the host and in virtual machines running Windows and Linux.\n\n### Prerequisites\n1. [Vagrant](https://www.vagrantup.com/)\n2. [VirtualBox](https://www.virtualbox.org/)\n3. The GPII CI Plugin: 'vagrant plugin install vagrant-gpii-ci'\n\n### Running Flocking's Test Suite\n\nRun all tests on your host:\n* `npm test`\n\nRun only browser tests:\n* `npm run browser-test`\n\nRun all VM-based tests:\n* `npm run all-vm-test`\n\nRun all tests on a Vagrant-based Windows VM:\n* `npm run windows-vm-test`\n\nRun all tests on a Linux VM:\n* `npm run linux-vm-test`\n\nStop all Vagrant VMs:\n* `vagrant halt`\n\nDestroy all Vagrant boxes, freeing up hard disk space:\n* `npm run destroy-vms`\n\nCompatibility\n-------------\n\nFlocking is currently tested on the latest versions of Firefox, Chrome, Safari, and Microsoft Edge\non Mac, Windows, Linux, iOS, and Android.\n\nLicense\n---------\n\nFlocking is distributed under the terms of both the MIT or GPL 2 Licenses.\nAs a result, you can choose the license that best suits your\nproject. The full text of Flocking's [MIT](MIT_LICENSE.txt) and [GPL](GPL-LICENSE.txt) licenses are at the root of the repository.\n\n\nCredits\n-------\n\nFlocking is developed by Colin Clark and the community.\nIt was named after a composition by [James Tenney](https://www.plainsound.org/JTwork.html),\na composer, thinker, and early pioneer of computer music who was my composition teacher and a\nhuge influence on my work. I hope you find this library useful enough to create projects as\nbeautiful and inspiring as Jim's _Flocking_.\n\n### Thanks to:\n * [Adam Tindale](http://adamtindale.com) for the tanh distortion unit generator, documentation improvements, and several of the Playground demos\n * [Alfredo Matas](https://github.com/amatas) for test automation on Windows and Linux\n * [Johnny Taylor](https://github.com/abledaccess) for styling improvements to the Playground\n * [Dan Stowell](https://github.com/danstowell) for the Freeverb and Delay1 unit generators\n * [Mayank Sanganeria](https://github.com/e7mac) for the \u003ccode\u003eflock.ugen.granulator\u003c/code\u003e unit generator\n * [Vitus](https://github.com/derDoc) for his contributions to the original version of the interactive Playground\n * [Myles Borins](https://github.com/thealphanerd) for pushing the limits of Flocking early in its development\n * [Antranig Basman](https://github.com/amb26) for code review, architectural advice, and help with maths\n * Alex Geddie for teaching me a ton about synthesis and computer music\n","funding_links":[],"categories":["Programming Languages","Sound creation"],"sub_categories":["Javascript","Instrument recordings"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolinbdclark%2FFlocking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcolinbdclark%2FFlocking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolinbdclark%2FFlocking/lists"}