{"id":12155,"library":"tone","title":"Tone.js","description":"Tone.js is a comprehensive Web Audio framework designed for creating interactive music directly within the browser. It provides high-level abstractions over the Web Audio API, offering a wide array of instruments (like Synths, Samplers), effects (Reverb, Delay), and advanced signal processing tools for dynamic audio manipulation. Currently stable at version 15.1.22, the library has seen consistent development, including a significant transition to TypeScript in its 14.7.x series, enhancing type safety and developer experience. Its release cadence is moderate, with major updates introducing new features and improvements, while also addressing breaking changes through version increments. Key differentiators include its robust scheduling system (`Tone.Transport`), extensive collection of DSP modules, and focus on real-time interactive performance, making it a popular choice for web-based musical applications and installations.","status":"active","version":"15.1.22","language":"javascript","source_language":"en","source_url":"https://github.com/Tonejs/Tone.js","tags":["javascript","Web Audio","Web Audio API","Synthesis","Playback","Effect","Instrument","DSP","Signal Processing","typescript"],"install":[{"cmd":"npm install tone","lang":"bash","label":"npm"},{"cmd":"yarn add tone","lang":"bash","label":"yarn"},{"cmd":"pnpm add tone","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Tone.js is primarily designed for ESM in modern usage, especially since v14.7.x's TypeScript conversion. CommonJS `require` is generally incorrect. The `import * as Tone` pattern is recommended for accessing the global Tone namespace.","wrong":"const Tone = require('tone');","symbol":"Tone","correct":"import * as Tone from 'tone';"},{"note":"Most classes and functions are available as named exports directly from the 'tone' package. Importing from deep paths like `tone/build/esm/...` is typically handled by bundlers and should be avoided in application code.","wrong":"import { Synth } from 'tone/build/esm/instrument/Synth';","symbol":"Synth","correct":"import { Synth, Destination, start } from 'tone';"},{"note":"To ensure audio playback, `Tone.start()` (or the named export `start()`) must be called after a user interaction (e.g., a button click). If importing `* as Tone`, you'd call `Tone.start()`. If using named imports, `start()` is directly available. Calling it without user interaction can lead to silent audio.","wrong":"Tone.start(); // after import * as Tone from 'tone'","symbol":"start","correct":"import { start, Transport } from 'tone';"}],"quickstart":{"code":"import { Synth, Destination, start, now, Transport } from 'tone';\n\nconst playButton = document.createElement('button');\nplayButton.textContent = 'Play Synth';\ndocument.body.appendChild(playButton);\n\nplayButton.addEventListener('click', async () => {\n  // Start the Tone.js audio context on user interaction\n  await start();\n  console.log('Audio context started.');\n\n  // Create a simple synthesizer\n  const synth = new Synth().toDestination();\n\n  // Schedule some notes\n  const synthNotes = [\n    { note: 'C4', time: 0, duration: '8n' },\n    { note: 'E4', time: '8n', duration: '8n' },\n    { note: 'G4', time: '4n', duration: '8n' },\n    { note: 'C5', time: '2n', duration: '8n' }\n  ];\n\n  Transport.scheduleOnce(() => {\n    synthNotes.forEach(event => {\n      synth.triggerAttackRelease(event.note, event.duration, now() + Transport.seconds + event.time);\n    });\n  }, 0); // Schedule immediately when transport starts\n\n  // Start the transport to play scheduled events\n  Transport.start();\n\n  console.log('Synth playing...');\n});\n","lang":"typescript","description":"This quickstart initializes Tone.js, creates a basic synthesizer, and schedules a short melody to play upon user interaction, demonstrating fundamental setup and event scheduling."},"warnings":[{"fix":"Use `Tone.connect(srcNode, destNode, [outputNum], [inputNum])` to connect native Web Audio nodes with Tone.js nodes. Ensure both nodes share the same AudioContext, which can be set using `Tone.setContext(audioContext)`.","message":"The way native Web Audio nodes connect to Tone.js nodes was changed in v13.8.25. `AudioNode.prototype.connect` is no longer overwritten, meaning direct `.connect()` calls between native and Tone.js nodes will fail.","severity":"breaking","affected_versions":">=13.8.25"},{"fix":"Migrate time expressions to object notation or compose them using arithmetic. For example, instead of `Tone.Time('4n * 2 + 3t')`, use `Time('4n') * 2 + Time('3t')` or `{'4n': 1, '8t': 2}` for durations.","message":"String expressions for `Tone.TimeBase` and related classes (e.g., '4n', '8t') were deprecated in v13.4.9 in favor of object notation. Direct string usage as time values may still work but is not the recommended or most performant approach for complex expressions.","severity":"breaking","affected_versions":">=13.4.9"},{"fix":"Always call `await Tone.start();` (or `await start();` with named imports) inside an event listener (e.g., `click`, `keydown`) before attempting to play any audio.","message":"Browsers require a user interaction (like a click or key press) to start the `AudioContext`. If `Tone.start()` is not called within an event listener triggered by user input, no audio will play.","severity":"gotcha","affected_versions":"All"},{"fix":"Replace all instances of `Tone.Master` with `Tone.Destination` (or `Destination` when using named imports). Ensure your instruments are routed to `Destination`.","message":"The global `Master` output was renamed to `Destination` in a pre-14.7.x release. Code referring to `Tone.Master` will no longer work.","severity":"breaking","affected_versions":">=14.0.0"},{"fix":"For JavaScript projects, ensure your bundler (e.g., Webpack, Rollup) is configured to handle ESM and potentially TypeScript outputs. For TypeScript projects, ensure `tsconfig.json` is correctly set up for module resolution (e.g., `\"moduleResolution\": \"bundler\"` or `\"node\"`).","message":"Tone.js was converted to TypeScript starting from version 14.7.x. While this improves type safety, it might affect existing JavaScript projects that relied on specific build processes or inferred types, and can sometimes lead to module resolution issues if not configured correctly.","severity":"breaking","affected_versions":">=14.7.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use the `Tone.connect()` helper function for connecting native Web Audio nodes with Tone.js nodes: `Tone.connect(nativeNode, toneNode);`.","cause":"Attempting to connect a native Web Audio `AudioNode` directly to a Tone.js node using the native `.connect()` method, which is no longer overwritten by Tone.js since v13.8.25.","error":"TypeError: Failed to execute 'connect' on 'AudioNode': parameter 1 is not of type 'AudioNode'."},{"fix":"Switch to ES Module import syntax: `import * as Tone from 'tone';` or `import { Synth } from 'tone';`. Ensure your `package.json` specifies `\"type\": \"module\"` if it's an ESM-only project.","cause":"Using CommonJS `require()` syntax in a modern project configured for ES Modules, or when Tone.js is intended to be imported as an ES Module.","error":"ReferenceError: require is not defined"},{"fix":"Update time expressions to use object notation or compose them arithmetically. For simple cases, `Tone.Time('4n')` would convert, or use `{ '4n': 1 }` directly as a duration parameter if the API accepts it.","cause":"Attempting to use a deprecated string expression for time/duration where an object notation or a different TimeExpression format is expected, especially after v13.4.9.","error":"Argument of type '\"4n\"' is not assignable to parameter of type 'TimeExpression | Object<string, number>'."},{"fix":"Wrap your `Tone.start()` call in a user-triggered event listener, such as a click handler: `document.getElementById('playButton').addEventListener('click', async () => { await Tone.start(); /* ... your audio code ... */ });`.","cause":"Attempting to play audio or start the Tone.js context before the user has interacted with the page, which is a browser security/policy restriction.","error":"The AudioContext was not allowed to start. It must be resumed (or created) after a user gesture on the page. https://goo.gl/7K7WLu"}],"ecosystem":"npm"}