@otoinki/offline-render

A Tone.Offline wrapper that runs renders one at a time and keeps the live context global, plus withLiveContext for building live nodes safely. 描画を一つずつ順に行い、グローバルな Tone のコンテキストを常にライブ側に保つ Tone.Offline の包みと、ライブのノードを安全に作る withLiveContext です。

Tone is passed in as a parameter, so the package has no runtime dependency and works with whichever tone version your app ships. Tone は引数で受け取るので、実行時の依存はなく、アプリが使う tone の版のまま動きます。

Install / インストール

npm install @otoinki/offline-render

Usage / 使い方

import * as Tone from 'tone';
import { renderOffline, withLiveContext } from '@otoinki/offline-render';

const buffer = await renderOffline(Tone, () => {
  new Tone.Synth().toDestination().triggerAttackRelease('C4', 0.5, 0);
}, 1);

Build every node before the callback's first await; after it, the global context is the live one again. ノードはすべて、コールバックの最初の await より前に作ってください。その後はグローバルなコンテキストがライブ側に戻っています。

Awaiting something at the end, such as await reverb.ready, is fine. If a node really must be created later, pass the context the callback receives (new Tone.Gain({ context })). 最後に await reverb.ready のように待つのは問題ありません。どうしても後でノードを作るときは、コールバックが受け取るコンテキストを渡してください（new Tone.Gain({ context })）。

API

• renderOffline(Tone, fn, duration, opts?) — runs Tone.Offline(fn, duration) one at a time per Tone namespace, and puts the live context back right after fn has run up to its first await and again after the render settles.
• renderOffline(Tone, fn, duration, opts?) — Tone.Offline(fn, duration) を Tone の名前空間ごとに一つずつ実行し、fn が最初の await まで進んだ直後と、描画が終わった後に、ライブのコンテキストを戻します。
• opts.liveContext — the context to restore; defaults to whatever is global when the render's turn comes. opts.channels and opts.sampleRate go straight to Tone.Offline.
• opts.liveContext — 戻す先のコンテキストです。省くと、その描画の順番が来た時点のグローバルなコンテキストになります。opts.channels と opts.sampleRate はそのまま Tone.Offline に渡します。
• withLiveContext(Tone, liveCtx, build) — runs build synchronously with liveCtx global, then restores the previous context, even if build throws.
• withLiveContext(Tone, liveCtx, build) — liveCtx をグローバルにした状態で build を同期的に実行し、build が例外を投げても元のコンテキストに戻します。
• OFFLINE_RENDER_API_VERSION — 1.
• OFFLINE_RENDER_API_VERSION — 1 です。

The full contract is in CONTRACT.md. 契約の全文は CONTRACT.md にあります。

Limitations / 限界

• Checked against tone 14.9.17 and 15.1.22 only; other versions are untested.
• 確かめたのは tone 14.9.17 と 15.1.22 だけで、ほかの版は試していません。
• Tests are not shipped in this package; they live in the source repository.
• テストはこのパッケージに含まれず、ソースのリポジトリにあります。
• The source repository is being prepared and is not public yet.
• ソースのリポジトリは準備中で、まだ公開していません。

Design background / 設計の背景

Tone.Offline sets the global context to a new OfflineContext and only puts the original back after the callback's first await resumes. Tone.Offline は、グローバルなコンテキストを新しい OfflineContext に替え、コールバックの最初の await が戻ってから元に戻します。

Live nodes built in that window land in the OfflineContext, and connecting them to the live graph throws "cannot connect to an AudioNode belonging to a different audio context". その間に作ったライブのノードは OfflineContext 側に入り、ライブのグラフにつなぐと「cannot connect to an AudioNode belonging to a different audio context」で失敗します。

Two overlapping calls can also leave the global context stuck on a finished OfflineContext. 二つの呼び出しが重なると、グローバルなコンテキストが描画済みの OfflineContext のまま残ることもあります。

Two apps in the same family had each fixed this on their own; this package is new code that collects those fixes in one place. 同じ一群の二つのアプリが、それぞれ別々にこれを直していました。このパッケージは、それを一か所にまとめた新しいコードです。

Licence

MIT. See LICENSE. MIT です。LICENSE を参照してください。