Voice limiting: the source
Open the live demo · Read the guide · View on GitHub
Regions the guide quotes: live (line 85), scene (line 185), crowd (line 190), read (line 197).
1/// How many sounds may play at once, and which ones win when more than that
2/// are asking to be heard.
3///
4/// Quoted by `voice_limit.md` and shown whole in the Source tab.
5library;
7import 'dart:math' as math;
9import 'package:flutter3d/flutter3d.dart';
10import 'package:flutter3d_audio/flutter3d_audio.dart';
11import 'package:flutter3d_showcase/src/demo/demo.dart';
12import 'package:flutter3d_showcase/src/demo/scene_kit.dart';
14/// The `voice-limit` page: footsteps and a shout asking for voices under a
15/// limit. Its check is that three voices go to exactly three of five sounds
16/// and that the higher priority wins.
17final class VoiceLimitDemo extends ShowcaseDemo {
18 late final String _report;
20 /// How many voices may play at once, 1 to 10.
21 double voices = 3.0;
23 /// How many footsteps ask for a voice, 0 to 12.
24 double asking = 8.0;
26 /// Whether a shout, with a higher priority than the footsteps, asks too.
27 bool shouting = true;
29 bool _dirty = true;
30 late final List<MeshNode> _balls;
31 late final MeshNode _shout;
32 late final BarGauge _granted;
34 static const int _most = 12;
37 void configureView(DemoContext context) {
38 context.orbit
39 ..distance = 14.0
40 ..pitch = 1.1
41 ..yaw = 0.0;
42 context.orbit.target.setValues(0.0, 0.0, 0.5);
43 }
46 Scene build(DemoContext context) {
47 _report = _run();
48 _balls = <MeshNode>[
49 for (var i = 0; i < _most; i++)
50 ballNode(context, 'step $i', 0.3, Vector4(0.3, 0.3, 0.33, 1.0)),
51 ];
52 _shout = ballNode(
53 context,
54 'shout',
55 0.55,
56 Vector4(0.3, 0.3, 0.33, 1.0),
57 at: Vector3(0.0, 0.55, -3.0),
58 );
59 _granted = BarGauge(
60 context,
61 'granted',
62 Vector4(0.7, 0.4, 0.8, 1.0),
63 Vector3(-5.0, 0.0, 5.5),
64 height: 10.0,
65 );
66 return sceneOf(<SceneNode>[
67 floorNode(context, width: 16.0, depth: 14.0),
68 blockNode(
69 context,
70 'listener',
71 Vector3(0.6, 0.6, 0.6),
72 Vector4(0.45, 0.65, 0.95, 1.0),
73 at: Vector3(0.0, 0.3, 0.0),
74 ),
75 ..._balls,
76 _shout,
77 ..._granted.nodes,
78 ]);
79 }
82 void update(DemoContext context, double dt) {
83 if (!_dirty) return;
84 _dirty = false;
85 // Ask again with whatever the sliders say: a scene with room for `voices`
86 // voices, a crowd of footsteps at growing distances, and a shout.
87 final AudioScene scene = AudioScene(
88 backend: SilentBackend(),
89 maxVoices: voices.round(),
90 );
91 const SoundDef footstep = SoundDef(
92 name: 'footstep',
93 asset: 'step.wav',
94 priority: 0,
95 );
96 const SoundDef shout = SoundDef(
97 name: 'shout',
98 asset: 'shout.wav',
99 priority: 10,
100 );
101 final List<AudioEmitter> steps = <AudioEmitter>[
102 for (var i = 0; i < asking.round(); i++)
103 scene.play(
104 footstep,
105 Vector3(
106 (1.5 + 0.35 * i) * math.cos(i * 2.4),
107 0.0,
108 (1.5 + 0.35 * i) * math.sin(i * 2.4),
109 ),
110 ),
111 ];
112 final AudioEmitter? loud = shouting
113 ? scene.play(shout, Vector3(0.0, 0.0, -3.0))
114 : null;
115 scene.update(AudioListener());
116 for (var i = 0; i < _most; i++) {
117 final bool asked = i < steps.length;
118 _balls[i].isVisible = asked;
119 if (!asked) continue;
120 final double angle = i * 2.4;
121 final double radius = 1.5 + 0.35 * i;
122 _balls[i].setPosition(
123 radius * math.cos(angle),
124 0.3,
125 radius * math.sin(angle),
126 );
127 _color(_balls[i], steps[i].audibleGain > 0.0, const <double>[
128 0.9,
129 0.75,
130 0.3,
131 ]);
132 }
133 _shout.isVisible = loud != null;
134 if (loud != null) {
135 _color(_shout, loud.audibleGain > 0.0, const <double>[0.85, 0.35, 0.3]);
136 }
137 _granted.set(scene.voiceCount / 10.0);
138 }
140 /// Lit in [lit] colours while it has a voice, dark once it has none.
141 void _color(MeshNode node, bool has, List<double> lit) {
142 node.material.baseColor = LinearColor.fromSrgb(
143 has ? lit[0] : 0.22,
144 has ? lit[1] : 0.22,
145 has ? lit[2] : 0.25,
146 1.0,
147 );
148 }
151 List<DemoControl> controls(DemoContext context) => <DemoControl>[
152 SliderControl(
153 'Voices allowed',
154 min: 1,
155 max: 10,
156 value: () => voices,
157 onChanged: (double v) {
158 voices = v.roundToDouble();
159 _dirty = true;
160 },
161 format: (double v) => v.round().toString(),
162 ),
163 SliderControl(
164 'Footsteps asking',
165 min: 0,
166 max: 12,
167 value: () => asking,
168 onChanged: (double v) {
169 asking = v.roundToDouble();
170 _dirty = true;
171 },
172 format: (double v) => v.round().toString(),
173 ),
174 ToggleControl(
175 'Add a shout',
176 value: () => shouting,
177 onChanged: (bool v) {
178 shouting = v;
179 _dirty = true;
180 },
181 ),
182 ];
184 static String _run() {
185 // A scene with room for three voices, asked for five.
186 final scene = AudioScene(backend: SilentBackend(), maxVoices: 3);
187 const footstep = SoundDef(name: 'footstep', asset: 'step.wav', priority: 0);
188 const shout = SoundDef(name: 'shout', asset: 'shout.wav', priority: 10);
190 for (var i = 0; i < 4; i++) {
191 scene.play(footstep, Vector3(i.toDouble(), 0.0, 0.0));
192 }
193 final loudOne = scene.play(shout, Vector3(0.0, 0.0, 3.0));
194 const requested = 5;
195 scene.update(AudioListener());
197 // A one-shot that lost the vote for a voice is dropped on the same
198 // update that decided it, which is why what is left over answers both
199 // questions at once.
200 final gotVoice = scene.voiceCount;
201 final shoutWon = loudOne.audibleGain > 0.0;
203 return '$gotVoice of $requested requested sounds got a voice; '
204 'the rest, being one-shots, are already gone\n'
205 'the higher-priority shout is one of them: $shoutWon';
206 }
209 void verify(Scene scene, FrameResult frame) {
210 if (frame.drawCalls < 1) {
211 throw StateError('the crowd marker was not drawn');
212 }
213 if (!_report.contains('3 of 5 requested sounds got a voice')) {
214 throw StateError(
215 'a scene limited to three voices should give exactly '
216 'three of five sounds one',
217 );
218 }
219 if (!_report.contains('is one of them: true')) {
220 throw StateError(
221 'a higher-priority sound should win a voice over a '
222 'lower-priority one',
223 );
224 }
225 }
226}