@@ -31,6 +31,10 @@ function createMockAudioContext(currentTime = 100) {
3131 gain : { value : 1 } ,
3232 connect : vi . fn ( ) ,
3333 } ;
34+ const monitorGain = {
35+ gain : { value : 1 } ,
36+ connect : vi . fn ( ) ,
37+ } ;
3438 const ctx = {
3539 currentTime,
3640 state : "running" ,
@@ -41,14 +45,15 @@ function createMockAudioContext(currentTime = 100) {
4145 destination : { } ,
4246 close : vi . fn ( ) ,
4347 } ;
44- return { ctx, sourceNode, mediaElementSourceNode, gainNode, masterGain, startFn } ;
48+ return { ctx, sourceNode, mediaElementSourceNode, gainNode, masterGain, monitorGain , startFn } ;
4549}
4650
4751function setupTransport ( currentTime = 100 ) {
4852 const transport = new WebAudioTransport ( ) ;
4953 const mock = createMockAudioContext ( currentTime ) ;
5054 ( transport as unknown as { _ctx : unknown } ) . _ctx = mock . ctx ;
5155 ( transport as unknown as { _masterGain : unknown } ) . _masterGain = mock . masterGain ;
56+ ( transport as unknown as { _monitorGain : unknown } ) . _monitorGain = mock . monitorGain ;
5257 const gen = transport . startGeneration ( ) ;
5358 return { transport, mock, gen } ;
5459}
@@ -87,12 +92,12 @@ describe("WebAudioTransport author gain vs user volume", () => {
8792
8893 it ( "keeps the user's master volume spec-clamped — it is a fader, not a gain" , ( ) => {
8994 const transport = new WebAudioTransport ( ) ;
90- const master = { gain : { value : 1 } , connect : vi . fn ( ) } ;
91- ( transport as unknown as { _masterGain : unknown } ) . _masterGain = master ;
95+ const monitor = { gain : { value : 1 } , connect : vi . fn ( ) } ;
96+ ( transport as unknown as { _monitorGain : unknown } ) . _monitorGain = monitor ;
9297
9398 transport . setVolume ( 99 ) ;
9499
95- expect ( master . gain . value ) . toBe ( 1 ) ;
100+ expect ( monitor . gain . value ) . toBe ( 1 ) ;
96101 } ) ;
97102} ) ;
98103
@@ -341,11 +346,13 @@ describe("WebAudioTransport", () => {
341346 const { transport, mock } = setupTransport ( ) ;
342347 transport . setVolume ( 0.4 ) ;
343348 transport . setMuted ( true ) ;
344- expect ( mock . masterGain . gain . value ) . toBe ( 0 ) ;
349+ expect ( mock . monitorGain . gain . value ) . toBe ( 0 ) ;
350+ expect ( mock . masterGain . gain . value ) . toBe ( 1 ) ;
345351
346352 transport . setMuted ( false ) ;
347353
348- expect ( mock . masterGain . gain . value ) . toBe ( 0.4 ) ;
354+ expect ( mock . monitorGain . gain . value ) . toBe ( 0.4 ) ;
355+ expect ( mock . masterGain . gain . value ) . toBe ( 1 ) ;
349356 } ) ;
350357
351358 it ( "applies author and user volume once in separate gain layers" , async ( ) => {
@@ -354,8 +361,11 @@ describe("WebAudioTransport", () => {
354361 transport . setVolume ( 0.5 ) ;
355362
356363 expect ( mock . gainNode . gain . value ) . toBe ( 0.8 ) ;
357- expect ( mock . masterGain . gain . value ) . toBe ( 0.5 ) ;
358- expect ( mock . gainNode . gain . value * mock . masterGain . gain . value ) . toBeCloseTo ( 0.4 ) ;
364+ expect ( mock . masterGain . gain . value ) . toBe ( 1 ) ;
365+ expect ( mock . monitorGain . gain . value ) . toBe ( 0.5 ) ;
366+ expect (
367+ mock . gainNode . gain . value * mock . masterGain . gain . value * mock . monitorGain . gain . value ,
368+ ) . toBeCloseTo ( 0.4 ) ;
359369 } ) ;
360370
361371 describe ( "ownsElement (per-element mute gate)" , ( ) => {
@@ -738,6 +748,7 @@ describe("WebAudioTransport", () => {
738748 getFloatTimeDomainData : ReturnType < typeof vi . fn > ;
739749 } [ ] = [ ] ;
740750 const masterGain = { gain : { value : 1 } , connect : vi . fn ( ) , disconnect : vi . fn ( ) } ;
751+ const monitorGain = { gain : { value : 1 } , connect : vi . fn ( ) , disconnect : vi . fn ( ) } ;
741752 const mediaElementSource = { connect : vi . fn ( ) , disconnect : vi . fn ( ) } ;
742753 const ctx = {
743754 currentTime,
@@ -784,21 +795,23 @@ describe("WebAudioTransport", () => {
784795 analysers . push ( node ) ;
785796 return node ;
786797 } ) ,
798+ createChannelSplitter : vi . fn ( ( ) => ( { connect : vi . fn ( ) , disconnect : vi . fn ( ) } ) ) ,
787799 // The media-element route needs this as much as the decoded one: without
788800 // it `scheduleMediaElementPlayback` throws and its catch returns null,
789801 // which reads as "the member did not play" rather than a missing stub.
790802 createMediaElementSource : vi . fn ( ( ) => mediaElementSource ) ,
791803 destination : { } ,
792804 close : vi . fn ( ) ,
793805 } ;
794- return { ctx, gainNodes, analysers, masterGain, mediaElementSource } ;
806+ return { ctx, gainNodes, analysers, masterGain, monitorGain , mediaElementSource } ;
795807 }
796808
797809 function setupGroupTransport ( currentTime = 100 ) {
798810 const transport = new WebAudioTransport ( ) ;
799811 const mock = createGroupMockAudioContext ( currentTime ) ;
800812 ( transport as unknown as { _ctx : unknown } ) . _ctx = mock . ctx ;
801813 ( transport as unknown as { _masterGain : unknown } ) . _masterGain = mock . masterGain ;
814+ ( transport as unknown as { _monitorGain : unknown } ) . _monitorGain = mock . monitorGain ;
802815 const gen = transport . startGeneration ( ) ;
803816 return { transport, mock, gen } ;
804817 }
@@ -1085,6 +1098,113 @@ describe("WebAudioTransport", () => {
10851098 expect ( ( ) => transport . setGroupMuted ( "never-played" , true ) ) . not . toThrow ( ) ;
10861099 } ) ;
10871100 } ) ;
1101+
1102+ describe ( "level metering" , ( ) => {
1103+ const addGroup = ( id : string ) => {
1104+ document . body . insertAdjacentHTML (
1105+ "beforeend" ,
1106+ `<hf-audio-group id="${ id } "></hf-audio-group>` ,
1107+ ) ;
1108+ } ;
1109+ const setLevel = ( analyser : { getFloatTimeDomainData : unknown } , peak : number ) => {
1110+ ( analyser . getFloatTimeDomainData as ReturnType < typeof vi . fn > ) . mockImplementation (
1111+ ( buf : Float32Array ) => buf . fill ( 0 ) . fill ( - peak , 3 , 4 ) ,
1112+ ) ;
1113+ } ;
1114+
1115+ it ( "creates nothing until startMetering" , async ( ) => {
1116+ addGroup ( "vo" ) ;
1117+ const { transport, mock, gen } = setupGroupTransport ( ) ;
1118+ await scheduleGrouped ( transport , gen , "a" , "vo" ) ;
1119+ expect ( mock . ctx . createAnalyser ) . not . toHaveBeenCalled ( ) ;
1120+ expect ( transport . readLevels ( ) ) . toEqual ( { master : { l : 0 , r : 0 } , groups : { } } ) ;
1121+ } ) ;
1122+
1123+ it ( "attaches the master tap once init() lands, even when startMetering ran while the context was still warming up" , async ( ) => {
1124+ const mock = createGroupMockAudioContext ( ) ;
1125+ class MockAudioContext {
1126+ constructor ( ) {
1127+ return mock . ctx as unknown as MockAudioContext ;
1128+ }
1129+ }
1130+ vi . stubGlobal ( "AudioContext" , MockAudioContext ) ;
1131+ const transport = new WebAudioTransport ( ) ;
1132+
1133+ transport . startMetering ( ) ;
1134+ expect ( mock . ctx . createAnalyser ) . not . toHaveBeenCalled ( ) ;
1135+ expect ( transport . readLevels ( ) ) . toEqual ( { master : { l : 0 , r : 0 } , groups : { } } ) ;
1136+
1137+ const ok = await transport . init ( ) ;
1138+
1139+ expect ( ok ) . toBe ( true ) ;
1140+ expect ( mock . ctx . createAnalyser ) . toHaveBeenCalled ( ) ;
1141+ expect ( transport . readLevels ( ) ) . toEqual ( { master : { l : 0 , r : 0 } , groups : { } } ) ;
1142+ vi . unstubAllGlobals ( ) ;
1143+ } ) ;
1144+
1145+ it ( "taps master and each group as side branches, once however often it starts" , async ( ) => {
1146+ addGroup ( "vo" ) ;
1147+ const { transport, mock, gen } = setupGroupTransport ( ) ;
1148+ await scheduleGrouped ( transport , gen , "a" , "vo" ) ;
1149+ const groupOutput = mock . gainNodes [ 2 ] ! ;
1150+ const connectsBefore = groupOutput . connect . mock . calls . length ;
1151+
1152+ transport . startMetering ( ) ;
1153+ transport . startMetering ( ) ;
1154+
1155+ expect ( mock . analysers ) . toHaveLength ( 4 ) ;
1156+ expect ( groupOutput . connect ) . toHaveBeenCalledTimes ( connectsBefore + 1 ) ;
1157+ expect ( groupOutput . connect ) . toHaveBeenCalledWith ( mock . masterGain ) ;
1158+ expect ( mock . masterGain . connect ) . toHaveBeenCalledTimes ( 1 ) ;
1159+ expect ( mock . monitorGain . connect ) . not . toHaveBeenCalled ( ) ;
1160+ } ) ;
1161+
1162+ it ( "keeps program taps off the monitor fader" , async ( ) => {
1163+ addGroup ( "vo" ) ;
1164+ const { transport, mock, gen } = setupGroupTransport ( ) ;
1165+ await scheduleGrouped ( transport , gen , "a" , "vo" ) ;
1166+ transport . startMetering ( ) ;
1167+ transport . setVolume ( 0.5 ) ;
1168+ transport . setMuted ( true ) ;
1169+ const groupOutput = mock . gainNodes . find ( ( n ) =>
1170+ n . connect . mock . calls . some ( ( call ) => call [ 0 ] === mock . masterGain ) ,
1171+ ) ;
1172+ expect ( mock . masterGain . gain . value ) . toBe ( 1 ) ;
1173+ expect ( groupOutput ?. gain . value ) . toBe ( 1 ) ;
1174+ expect ( mock . monitorGain . gain . value ) . toBe ( 0 ) ;
1175+ } ) ;
1176+
1177+ it ( "reads the peak per channel and stops cleanly" , async ( ) => {
1178+ addGroup ( "vo" ) ;
1179+ const { transport, mock, gen } = setupGroupTransport ( ) ;
1180+ await scheduleGrouped ( transport , gen , "a" , "vo" ) ;
1181+ transport . startMetering ( ) ;
1182+ const [ masterL , , groupL , groupR ] = mock . analysers ;
1183+ setLevel ( masterL ! , 0.5 ) ;
1184+ setLevel ( groupL ! , 0.25 ) ;
1185+ setLevel ( groupR ! , 0.125 ) ;
1186+
1187+ const levels = transport . readLevels ( ) ;
1188+ expect ( levels . master ) . toEqual ( { l : 0.5 , r : 0 } ) ;
1189+ expect ( levels . groups . vo ) . toEqual ( { l : 0.25 , r : 0.125 } ) ;
1190+
1191+ transport . stopMetering ( ) ;
1192+ expect ( transport . readLevels ( ) ) . toEqual ( { master : { l : 0 , r : 0 } , groups : { } } ) ;
1193+ expect ( mock . gainNodes [ 2 ] ! . disconnect ) . toHaveBeenCalled ( ) ;
1194+ } ) ;
1195+
1196+ it ( "a group built after start is metered, and one removed from the document leaves the read" , async ( ) => {
1197+ const { transport, mock, gen } = setupGroupTransport ( ) ;
1198+ transport . startMetering ( ) ;
1199+ addGroup ( "late" ) ;
1200+ await scheduleGrouped ( transport , gen , "a" , "late" ) ;
1201+ expect ( Object . keys ( transport . readLevels ( ) . groups ) ) . toEqual ( [ "late" ] ) ;
1202+
1203+ document . querySelector ( "hf-audio-group" ) ! . remove ( ) ;
1204+ expect ( transport . readLevels ( ) . groups ) . toEqual ( { } ) ;
1205+ expect ( mock . analysers ) . toHaveLength ( 4 ) ;
1206+ } ) ;
1207+ } ) ;
10881208 } ) ;
10891209
10901210 describe ( "decodeAudioElement retry policy (late-asset self-heal)" , ( ) => {
0 commit comments