flutter3d
Showcase Changelog 62 packages API reference

Positional audio: the source

since 0.1.0 Simulation, audio and XR

Regions the guide quotes: live (line 94), hear (line 123), scene (line 169), play (line 173), move (line 180).

1/// A sound placed somewhere in the world, heard louder or softer and panned
2/// left or right depending on where the listener stands and faces.
3///
4/// A `SilentBackend` runs this page: it makes no sound and records every
5/// voice it is asked for, which is what lets the numbers below be checked
6/// without a speaker or a browser's audio stack.
7///
8/// Quoted by `positional_audio.md` and shown whole in the Source tab.
9library;
11import 'dart:math' as math;
13import 'package:flutter3d/flutter3d.dart';
14import 'package:flutter3d_audio/flutter3d_audio.dart';
15import 'package:flutter3d_showcase/src/demo/demo.dart';
16import 'package:flutter3d_showcase/src/demo/scene_kit.dart';
18/// The `positional-audio` page: a bell placed around a listener on a silent
19/// backend that records its voices. Its check is that a bell straight to the
20/// right pans hard right.
21final class PositionalAudioDemo extends ShowcaseDemo {
22 late final String _report;
24 /// How far the bell is from the listener, in metres, 0.5 to 12.
25 double distance = 4.0;
27 /// Where the bell stands around the listener, in degrees, -180 to 180;
28 /// advanced 25 degrees a second while [orbiting].
29 double angle = 0.0;
31 /// Whether the bell walks round the listener; dragging the angle stops it.
32 bool orbiting = true;
34 /// Whether the listener faces a quarter turn away from the bell.
35 bool turnedAway = false;
37 late final AudioEmitter _emitter;
38 late final AudioScene _audio;
39 late final AudioListener _listener;
40 late final MeshNode _source;
41 late final MeshNode _head;
42 late final BarGauge _gain;
43 late final RailGauge _pan;
45 @override
46 void configureView(DemoContext context) {
47 context.orbit
48 ..distance = 13.0
49 ..pitch = 0.95
50 ..yaw = 0.0;
51 context.orbit.target.setValues(0.0, 0.0, 1.5);
52 }
54 @override
55 Scene build(DemoContext context) {
56 _report = _run();
57 _source = ballNode(
58 context,
59 'source',
60 0.5,
61 Vector4(0.9, 0.75, 0.3, 1.0),
62 at: Vector3(0.0, 0.5, 0.0),
63 );
64 _head = blockNode(
65 context,
66 'listener',
67 Vector3(0.7, 0.7, 0.7),
68 Vector4(0.45, 0.65, 0.95, 1.0),
69 );
70 // A nose, so it is clear which way the listener faces.
71 _head.add(
72 blockNode(
73 context,
74 'nose',
75 Vector3(0.2, 0.2, 0.4),
76 Vector4(0.95, 0.95, 0.98, 1.0),
77 at: Vector3(0.0, 0.0, -0.5),
78 ),
79 );
80 _gain = BarGauge(
81 context,
82 'gain',
83 Vector4(0.9, 0.75, 0.3, 1.0),
84 Vector3(-3.0, 0.0, 6.0),
85 height: 6.0,
86 );
87 _pan = RailGauge(
88 context,
89 'pan',
90 Vector4(0.45, 0.65, 0.95, 1.0),
91 Vector3(0.0, 0.0, 7.2),
92 );
94 // The same scene as above, asked again every frame: the listener moves
95 // and turns, and what it would hear is read back off the emitter.
96 _audio = AudioScene(backend: SilentBackend());
97 _emitter = _audio.play(
98 const SoundDef(name: 'bell', asset: 'bell.wav'),
99 Vector3(0.0, 0.0, 0.0),
100 );
101 _listener = AudioListener();
102 return sceneOf(<SceneNode>[
103 floorNode(context, width: 18.0, depth: 18.0),
104 _source,
105 _head,
106 ..._gain.nodes,
107 ..._pan.nodes,
108 ]);
109 }
111 @override
112 void update(DemoContext context, double dt) {
113 if (orbiting) angle = (angle + 25.0 * dt + 180.0) % 360.0 - 180.0;
114 final double a = angle * math.pi / 180.0;
115 final Vector3 at = Vector3(
116 distance * math.cos(a),
117 0.0,
118 distance * math.sin(a),
119 );
120 // Facing the source, or a quarter turn from it.
121 final double toward = math.atan2(at.x, at.z);
122 final double yaw = toward + (turnedAway ? math.pi / 2 : 0.0);
123 _listener.aimAt(at, yaw);
124 _audio.update(_listener);
125 _head
126 ..setPosition(at.x, 0.35, at.z)
127 ..setRotationYawPitchRoll(yaw, 0.0, 0.0);
128 final double loud = _emitter.audibleGain;
129 _source.setUniformScale(0.6 + 0.9 * loud);
130 _source.setPosition(0.0, 0.5 * (0.6 + 0.9 * loud), 0.0);
131 _gain.set(loud);
132 _pan.set(_emitter.pan);
133 }
135 @override
136 List<DemoControl> controls(DemoContext context) => <DemoControl>[
137 SliderControl(
138 'Distance',
139 min: 0.5,
140 max: 12.0,
141 value: () => distance,
142 onChanged: (double v) => distance = v,
143 format: (double v) => '${v.toStringAsFixed(1)} m',
144 ),
145 SliderControl(
146 'Angle',
147 min: -180.0,
148 max: 180.0,
149 value: () => angle,
150 onChanged: (double v) {
151 orbiting = false;
152 angle = v;
153 },
154 format: (double v) => '${v.round()}°',
155 ),
156 ToggleControl(
157 'Walk round it',
158 value: () => orbiting,
159 onChanged: (bool v) => orbiting = v,
160 ),
161 ToggleControl(
162 'Turn away',
163 value: () => turnedAway,
164 onChanged: (bool v) => turnedAway = v,
165 ),
166 ];
168 static String _run() {
169 final backend = SilentBackend();
170 final scene = AudioScene(backend: backend);
171 const bell = SoundDef(name: 'bell', asset: 'bell.wav');
173 final emitter = scene.play(bell, Vector3(4.0, 0.0, 0.0));
174 final listener = AudioListener()..aimAt(Vector3.zero(), 0.0);
175 scene.update(listener);
177 final farGain = emitter.audibleGain;
178 final farPan = emitter.pan;
180 // The listener turns to face the source directly and steps closer.
181 listener.aimAt(Vector3(2.0, 0.0, 0.0), -1.5707963267948966);
182 scene.update(listener);
184 return 'four metres to the side: gain ${farGain.toStringAsFixed(3)}, '
185 'pan ${farPan.toStringAsFixed(2)}\n'
186 'two metres away and facing it: gain '
187 '${emitter.audibleGain.toStringAsFixed(3)}, pan '
188 '${emitter.pan.toStringAsFixed(2)}';
189 }
191 @override
192 void verify(Scene scene, FrameResult frame) {
193 if (frame.drawCalls < 1) {
194 throw StateError('the source marker was not drawn');
195 }
196 if (!_report.contains('pan 1.00')) {
197 throw StateError(
198 'a source straight to the right of the listener '
199 'should pan hard right',
200 );
201 }
202 }