The Flocking source code is hosted on Github, a community for sharing and contributing code using the Git distributed version control system. In the long run, you'll find that learning how to use Github and Git will be very helpful in using Flocking and other open source web toolkits. But it's not required. Here's how to get started with Flocking without using Git or Github.
- Go to the main Flocking page on Github
- Press the "Download ZIP" button to download the Flocking source code to your computer
- Unzip Flocking and copy the dist directory into your project. You'll probably want to rename it to flocking or the something more descriptive.
- Link the Flocking JavaScript file flocking-all.js to your web page using a script tag. This file contains all of Flocking packaged up as a single JavaScript file.
Here's how:
<!-- This includes Flocking and all its dependencies, including jQuery 2.0 and Infusion 1.5 -->
<script src="flocking/flocking-all.js"></script>
Here is an example of an HTML page that uses Flocking, which you can use as a template for your own projects:
<!DOCTYPE html>
<html lang="en">
<head>
<title>A Flocking Project</title>
<script src="flocking/flocking-all.js"></script>
<script src="myStuff.js"></script>
</head>
<body>
<!-- Your markup goes here -->
<script>
myStuff.play();
</script>
</body>
</html>
And an example JavaScript file:
// Wrap everything in a function to keep your stuff private.
(function () {
// JavaScript strict mode is a good thing.
"use strict";
// Define a unique global namespace for your stuff.
// You should change this to a namespace that is appropriate for your project.
fluid.registerNamespace("myStuff");
// Expose any public functions or constructors as properties on your namesapce.
myStuff.play = function () {
var mySynth = flock.synth({
synthDef: {
ugen: "flock.ugen.sin",
freq: {
ugen: "flock.ugen.lfNoise",
freq: 10,
mul: 380,
add: 60
},
mul: 0.1
}
});
// If you're on iOS, you will need to call in a listener for
// some kind of user input action, such a button click or touch handler.
// This is because iOS will only play sound if the user initiated it.
flock.enviro.shared.play();
};
}());
Flocking is hosted on Github. Here's how to get started:
- Clone the Flocking repository
- Run npm install to install Flocking's dependencies
- Run grunt to make a build of Flocking
- Copy the dist directory into your project. You probably will want to rename it to something like flocking
- Use the flocking-all.js for development for flocking-all.min.js for production.
- The other two files, flocking-audiofile-worker.js and flocking-audiofile.js will be loaded automatically into a Web Worker when decoding audio files.
Concatenated and minified Flocking files are committed to the source code repository, and can also be built manually using Grunt. Here's how to link to them in your page:
<!-- This includes Flocking and all its dependencies, including jQuery 2.0 and Infusion 1.5 -->
<script src="flocking-all.js"></script>
If you'd prefer to link to the individual Flocking files during development, these are the basic required dependencies:
<!-- jQuery -->
<script src="flocking/third-party/jquery/js/jquery.js"></script>
<!-- Infusion -->
<script src="flocking/third-party/infusion/js/Fluid.js"></script>
<script src="flocking/third-party/infusion/js/FluidIoC.js"></script>
<script src="flocking/third-party/infusion/js/DataBinding.js"></script>
<!-- The DSP API Polyfill -->
<script src="flocking/third-party/dspapi/js/dspapi.js"></script>
<!-- Flocking -->
<script src="flocking/flocking/flocking-core.js"></script>
<script src="flocking/flocking/flocking-scheduler.js"></script>
<script src="flocking/flocking/flocking-webaudio.js"></script>
<script src="flocking/flocking/flocking-parser.js"></script>
<script src="flocking/flocking/flocking-ugens.js"></script>
<script src="flocking/flocking/flocking-ugens-browser.js"></script>
In addition, if you're working with WAV or AIFF files, these files are required:
<script src="../../../flocking/flocking-buffers.js"></script>
<script src="../../../flocking/flocking-audiofile.js"></script>
If you're using the flock.ugen.scope unit generator, you'll also need:
<script src="../../../flocking/flocking-gfx.js"></script>
Infusion is a framework for building applications in JavaScript. Flocking itself is built with Infusion, and it provides much of the core flexibility and social opportunities that Flocking aspires to.
Fluid components are created by defining JSON "component trees", which are managed by an Inversion of Control system that is responsible for wiring up dependencies between components. Here's an example of how you would use Flocking with Infusion.
(function () {
// Define a unique global namespace for your stuff.
// You should change this to a namespace that is appropriate for your project.
fluid.registerNamespace("myStuff");
// Define an Infusion component that represents your instrument.
fluid.defaults("myStuff.sinewaver", {
// This instrument is a flock.synth, and ask Infusion to automatically
// define an initialization function for it.
gradeNames: ["flock.synth", "autoInit"],
// Define the synthDef for your instrument.
synthDef: {
id: "carrier",
ugen: "flock.ugen.sin",
freq: 220,
mul: 0.5
}
});
// Define an Infusion component that represents your composition,
// and which will contain instruments, a scheduler, and score.
fluid.defaults("myStuff.composition", {
gradeNames: ["fluid.eventedComponent", "autoInit"],
// This composition has two components:
// 1. our sinewaver instrument (defined above)
// 2. a tempo scheduler running at 60 bpm
components: {
instrument: {
type: "myStuff.sinewaver"
},
clock: {
type: "flock.scheduler.async.tempo",
options: {
bpm: 60
}
}
},
// The score is a declarative specification that can be passed to
// Scheduler.schedule(). In this case, the pitch will change every
// beat until it hits 1210 Hz, and then it will fade out.
score: [
{
// Schedule this event as repeating
interval: "repeat",
// Every beat.
time: 1.0,
change: {
// This specifies that we want to send the change to the "sinewaver" synth.
synth: "sinewaver",
values: {
"carrier.freq": {
// This creates a "value Synth" that will be evaluated every time the scheduler ticks.
// The value synth contains a single unit generator, sequence, which will read through
// the specified list.
synthDef: {
ugen: "flock.ugen.sequence",
list: [330, 440, 550, 660, 880, 990, 1100, 1210]
}
}
}
}
},
{
// Schedule this event only once
interval: "once",
// After 8 beats.
time: 8,
change: {
synth: "sinewaver",
// Inject a new "line" unit generator to fade out.
values: {
"carrier.mul": {
ugen: "flock.ugen.line",
start: 0.25,
end: 0.0,
duration: 1.0
}
}
}
}
],
// This section registers listeners for our composition's "onCreate" event,
// which is one of the built-in lifecycle events for Infusion.
// When onCreate fires, we start the environment and then schedule our score with the Scheduler.
listeners: {
onCreate: [
{
funcName: "flock.enviro.shared.play"
},
{
funcName: "{clock}.schedule",
args: ["{composition}.options.score"]
}
]
}
});
}());
And here's the HTML page to go with it:
<!DOCTYPE html>
<html lang="en">
<head>
<title>A Flocking Project</title>
<script src="flocking/flocking-all.js"></script>
<script src="myStuff.js"></script>
</head>
<body>
<!-- Your markup goes here -->
<script>
myStuff.composition();
</script>
</body>
</html>