agora-appbuilder-core 4.1.23 → 4.1.24-beta.2

package/template/src/pages/video-call/VideoRenderer.tsx

@@ -247,10 +247,12 @@ const VideoRenderer: React.FC<VideoRendererProps> = ({
             uid={user.uid}
             hasLeadingIcon={
               currentLayout === DefaultLayouts[1].name &&
+              !isMax &&
               user.uid === secondaryPinnedUid
             }
           />
           {currentLayout === DefaultLayouts[1].name &&
+          !isMax &&
           user.uid === secondaryPinnedUid ? (
             <View
               style={{

package/template/src/subComponents/caption/Transcript.tsx

@@ -40,6 +40,8 @@ import {
   sttTranscriptPanelSearchText,
   sttTranscriptPanelViewLatestText,
 } from '../../../src/language/default-labels/videoCallScreenLabels';
+import {logger, LogSource} from '../../logger/AppBuilderLogger';
+import {TRANSCRIPT_JOURNEY} from './transcriptJourney';
 
 export interface TranscriptProps {
   showHeader?: boolean;
@@ -56,6 +58,7 @@ const Transcript = (props: TranscriptProps) => {
     isSTTActive,
     selectedTranslationLanguage,
     transcriptViewMode,
+    isSTTListenerAdded,
   } = useCaption();
 
   const settingSpokenLanguageLabel = useString(sttSettingSpokenLanguageText)();
@@ -68,6 +71,39 @@ const Transcript = (props: TranscriptProps) => {
 
   const data = meetingTranscript; // Object.entries(transcript);
   console.log('[STT_GLOBAL] meetingTranscript data: ', data);
+  const hasLoggedFirstEntryRef = React.useRef(false);
+  const transcriptEntryCountRef = React.useRef(data.length);
+  transcriptEntryCountRef.current = data.length;
+
+  React.useEffect(() => {
+    logger.log(
+      LogSource.Internals,
+      'TRANSCRIPT',
+      `${TRANSCRIPT_JOURNEY} transcript panel state`,
+      {
+        stage: 'transcript_panel',
+        isSTTActive,
+        listenerRegistered: isSTTListenerAdded,
+        transcriptEntryCount: transcriptEntryCountRef.current,
+      },
+    );
+  }, [isSTTActive, isSTTListenerAdded]);
+
+  React.useEffect(() => {
+    if (data.length > 0 && !hasLoggedFirstEntryRef.current) {
+      hasLoggedFirstEntryRef.current = true;
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} first transcript entry available to panel`,
+        {
+          stage: 'transcript_panel_data',
+          outcome: 'success',
+          transcriptEntryCount: data.length,
+        },
+      );
+    }
+  }, [data.length]);
 
   const [showButton, setShowButton] = React.useState(false);
 

package/template/src/subComponents/caption/__tests__/transcriptJourney.test.ts

@@ -0,0 +1,7 @@
+import {TRANSCRIPT_JOURNEY} from '../transcriptJourney';
+
+describe('transcript journey logging', () => {
+  it('uses one searchable prefix', () => {
+    expect(TRANSCRIPT_JOURNEY).toBe('[TRANSCRIPT_JOURNEY]');
+  });
+});

package/template/src/subComponents/caption/transcriptJourney.ts

@@ -0,0 +1 @@
+export const TRANSCRIPT_JOURNEY = '[TRANSCRIPT_JOURNEY]';

package/template/src/subComponents/caption/useCaption.tsx

@@ -21,6 +21,7 @@ import {useRoomInfo} from '../../components/room-info/useRoomInfo';
 import {useContent, useRtc} from 'customization-api';
 import useStreamMessageUtils from './useStreamMessageUtils';
 import {isWebInternal} from '../../utils/common';
+import {TRANSCRIPT_JOURNEY} from './transcriptJourney';
 
 // Types
 type GlobalSttState = {
@@ -348,17 +349,58 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
       return;
     }
 
-    transcriptListenerSubscriptionRef.current = RtcEngineUnsafe.addListener(
-      'onStreamMessage',
-      handleStreamMessageCallback,
+    logger.log(
+      LogSource.Internals,
+      'TRANSCRIPT',
+      `${TRANSCRIPT_JOURNEY} stream listener registration requested`,
+      {stage: 'listener_registration', outcome: 'started'},
     );
-    setIsSTTListenerAdded(true);
+    try {
+      transcriptListenerSubscriptionRef.current = RtcEngineUnsafe.addListener(
+        'onStreamMessage',
+        handleStreamMessageCallback,
+      );
+      setIsSTTListenerAdded(true);
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} stream listener registered`,
+        {stage: 'listener_registration', outcome: 'success'},
+      );
+    } catch (error) {
+      logger.error(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} stream listener registration failed`,
+        {
+          stage: 'listener_registration',
+          outcome: 'failure',
+          error: error ?? null,
+        },
+      );
+    }
   }, [RtcEngineUnsafe, callActive, handleStreamMessageCallback]);
 
   React.useEffect(() => {
     return () => {
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} stream listener cleanup requested`,
+        {
+          stage: 'listener_cleanup',
+          outcome: 'started',
+          listenerReferencePresent: !!transcriptListenerSubscriptionRef.current,
+        },
+      );
       transcriptListenerSubscriptionRef.current?.remove();
       transcriptListenerSubscriptionRef.current = null;
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} stream listener subscription remove called and local reference cleared`,
+        {stage: 'listener_cleanup', outcome: 'completed'},
+      );
     };
   }, []);
 
@@ -409,6 +451,31 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
     sttDepsReadyRef.current = sttDepsReady;
   }, [sttDepsReady]);
 
+  React.useEffect(() => {
+    logger.log(
+      LogSource.Internals,
+      'TRANSCRIPT',
+      `${TRANSCRIPT_JOURNEY} STT readiness changed`,
+      {
+        stage: 'stt_readiness',
+        outcome: sttDepsReady ? 'ready' : 'waiting',
+        localUidReady: !!localUid,
+        localBotUidReady: !!localBotUid,
+        rtmJoined: !!hasUserJoinedRTM,
+        callActive: !!callActive,
+        roomInfoReady: !!(roomId?.host || roomId?.attendee),
+        listenerRegistered: !!transcriptListenerSubscriptionRef.current,
+      },
+    );
+  }, [
+    callActive,
+    hasUserJoinedRTM,
+    localBotUid,
+    localUid,
+    roomId,
+    sttDepsReady,
+  ]);
+
   React.useEffect(() => {
     if (sttDepsReadyRef.current && !hasFlushedSttQueueRef.current) {
       hasFlushedSttQueueRef.current = true;
@@ -526,22 +593,21 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
     try {
       setIsLangChangeInProgress(true);
       const result = await start(localBotUidRef.current, newConfig);
-      console.log('[STT] start result: ', result);
       if (result.success) {
         setIsSTTError(false);
         logger.log(
           LogSource.NetworkRest,
           'stt',
-          'STT started successfully',
-          result.data,
+          `${TRANSCRIPT_JOURNEY} STT started successfully`,
+          result.data ?? null,
         );
       } else {
         setIsSTTError(true);
         logger.error(
           LogSource.NetworkRest,
           'stt',
-          'Failed to start STT',
-          result.error,
+          `${TRANSCRIPT_JOURNEY} failed to start STT`,
+          result.error ?? null,
         );
         Toast.show({
           leadingIconName: 'alert',
@@ -558,7 +624,12 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
     } catch (error: any) {
       setIsLangChangeInProgress(false);
       setIsSTTError(true);
-      logger.error(LogSource.NetworkRest, 'stt', 'STT start error', error);
+      logger.error(
+        LogSource.NetworkRest,
+        'stt',
+        `${TRANSCRIPT_JOURNEY} STT start error`,
+        error ?? null,
+      );
       // Show error toast: text1 = translated label, text2 = exception error
       Toast.show({
         leadingIconName: 'alert',
@@ -603,16 +674,16 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
         logger.log(
           LogSource.NetworkRest,
           'stt',
-          'STT updated successfully',
-          result.data,
+          `${TRANSCRIPT_JOURNEY} STT updated successfully`,
+          result.data ?? null,
         );
       } else {
         setIsSTTError(true);
         logger.error(
           LogSource.NetworkRest,
           'stt',
-          'Failed to update STT',
-          result.error,
+          `${TRANSCRIPT_JOURNEY} failed to update STT`,
+          result.error ?? null,
         );
         // Show error toast: text1 = translated label, text2 = API error
         Toast.show({
@@ -630,7 +701,12 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
     } catch (error: any) {
       setIsLangChangeInProgress(false);
       setIsSTTError(true);
-      logger.error(LogSource.NetworkRest, 'stt', 'STT update error', error);
+      logger.error(
+        LogSource.NetworkRest,
+        'stt',
+        `${TRANSCRIPT_JOURNEY} STT update error`,
+        error ?? null,
+      );
       // Show error toast: text1 = translated label, text2 = exception error
       Toast.show({
         leadingIconName: 'alert',
@@ -649,10 +725,20 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
   };
 
   const stopSTTBotSession = React.useCallback(async () => {
-    console.log('[STT] stopSTTBotSession called');
+    logger.log(
+      LogSource.Internals,
+      'TRANSCRIPT',
+      `${TRANSCRIPT_JOURNEY} STT stop requested`,
+      {stage: 'stt_stop', localBotUid: localBotUidRef.current ?? null},
+    );
 
     if (!localBotUidRef.current) {
-      console.warn('[STT] Missing botUid for stop');
+      logger.warn(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} STT stop skipped because bot UID is missing`,
+        {stage: 'stt_stop', outcome: 'skipped'},
+      );
       return;
     }
 
@@ -668,16 +754,16 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
         logger.log(
           LogSource.NetworkRest,
           'stt',
-          'STT stopped successfully',
-          result.data,
+          `${TRANSCRIPT_JOURNEY} STT stopped successfully`,
+          result.data ?? null,
         );
       } else {
         setIsSTTError(true);
         logger.error(
           LogSource.NetworkRest,
           'stt',
-          'Failed to stop STT',
-          result.error,
+          `${TRANSCRIPT_JOURNEY} failed to stop STT`,
+          result.error ?? null,
         );
       }
     } catch (error) {
@@ -685,8 +771,8 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
       logger.error(
         LogSource.NetworkRest,
         'stt',
-        'Error in stopSTTBotSession',
-        error,
+        `${TRANSCRIPT_JOURNEY} error in stopSTTBotSession`,
+        error ?? null,
       );
     }
   }, [stop]);
@@ -757,12 +843,29 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
         // Queue
         enqueueSttEvent(updatedState, true, targetChange);
 
-        console.log(
-          '[STT_GLOBAL] confirmSpokenLanguageChange sent STT_GLOBAL_STATE: ',
-          updatedState,
+        logger.log(
+          LogSource.Internals,
+          'TRANSCRIPT',
+          `${TRANSCRIPT_JOURNEY} local spoken-language state queued`,
+          {
+            stage: 'global_state_queue',
+            outcome: 'queued',
+            spokenLanguage: updatedState.globalSpokenLanguage ?? null,
+            translationTargetCount:
+              updatedState.globalTranslationTargets.length,
+          },
         );
       } catch (error) {
-        console.log('[STT_GLOBAL] confirmSpokenLanguageChange error: ', error);
+        logger.error(
+          LogSource.Internals,
+          'TRANSCRIPT',
+          `${TRANSCRIPT_JOURNEY} local spoken-language state failed`,
+          {
+            stage: 'global_state_queue',
+            outcome: 'failure',
+            error: error ?? null,
+          },
+        );
       }
     },
     [localUid], // only real dependency
@@ -817,15 +920,24 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
   // Queues all local + remote stt events
   const enqueueSttEvent = React.useCallback(
     (state: GlobalSttState, isLocal: boolean, targetChange?: TargetChange) => {
-      console.log(
-        '[STT_GLOBAL] inside enqueueSttEvent - sttDepsReadyRef flag',
-        sttDepsReadyRef.current,
-      );
       sttEventQueueRef.current.push({
         state,
         isLocal,
         targetChange,
       });
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} STT global state queued`,
+        {
+          stage: 'global_state_queue',
+          outcome: 'queued',
+          stateOrigin: isLocal ? 'local' : 'remote',
+          sttEnabled: state.globalSttEnabled,
+          sttDepsReady: sttDepsReadyRef.current,
+          queueSize: sttEventQueueRef.current.length,
+        },
+      );
       if (sttDepsReadyRef.current) {
         processSttEventQueue();
       }
@@ -852,7 +964,12 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
         !globalSttStateRef.current.globalSttEnabled &&
         sttEventQueueRef.current.length === 0
       ) {
-        console.log('[STT] AUTO_START  injecting auto start state');
+        logger.log(
+          LogSource.Internals,
+          'TRANSCRIPT',
+          `${TRANSCRIPT_JOURNEY} STT auto-start state injected`,
+          {stage: 'global_state_queue', outcome: 'queued'},
+        );
 
         sttAutoStartGuardRef.current = true;
 
@@ -879,7 +996,12 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
       const {state: newState, isLocal, targetChange} = item;
       const prevState = globalSttStateRef.current;
       if (isSameState(prevState, newState)) {
-        console.log('[STT] Skipped duplicate STT_GLOBAL_STATE');
+        logger.log(
+          LogSource.Internals,
+          'TRANSCRIPT',
+          `${TRANSCRIPT_JOURNEY} duplicate STT global state skipped`,
+          {stage: 'global_state_queue', outcome: 'skipped'},
+        );
         continue; // no call to processGlobalSttSingleEvent
       }
       const ok = await processGlobalSttSingleEvent(
@@ -889,16 +1011,22 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
       );
       if (!ok) {
         if (isLocal) {
-          console.warn(
-            '[STT] Skipping local global state update because API failed.',
+          logger.warn(
+            LogSource.Internals,
+            'TRANSCRIPT',
+            `${TRANSCRIPT_JOURNEY} local global state update skipped because API failed`,
+            {stage: 'global_state_apply', outcome: 'skipped'},
           );
           continue;
         }
         // A received RTM event is authoritative for the meeting-level state.
         // Failure to provision this participant's bot must not make the UI
         // report that meeting STT is disabled while captions are arriving.
-        console.warn(
-          '[STT] Applying remote global state after local STT API failure.',
+        logger.warn(
+          LogSource.Internals,
+          'TRANSCRIPT',
+          `${TRANSCRIPT_JOURNEY} remote global state applied after local STT API failure`,
+          {stage: 'global_state_apply', outcome: 'applied_with_api_failure'},
         );
       }
       // update global state AFTER processing
@@ -923,10 +1051,24 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
       const isStopOperation = wasEnabledBefore && !isEnabledNow;
       try {
         if (isStartOperation) {
-          console.log('[STT] Remote global STT -> starting session', newState);
+          logger.log(
+            LogSource.Internals,
+            'TRANSCRIPT',
+            `${TRANSCRIPT_JOURNEY} STT global state selected start operation`,
+            {
+              stage: 'global_state_operation',
+              outcome: 'started',
+              stateOrigin: isLocal ? 'local' : 'remote',
+            },
+          );
           // Start guard starts
           if (sttStartGuardRef.current) {
-            console.log('[STT] Start skipped (already started)');
+            logger.log(
+              LogSource.Internals,
+              'TRANSCRIPT',
+              `${TRANSCRIPT_JOURNEY} STT start skipped by start guard`,
+              {stage: 'global_state_operation', outcome: 'skipped'},
+            );
             return;
           }
           sttStartGuardRef.current = true;
@@ -997,7 +1139,16 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
           }
           return true;
         } else if (isUpdateOperation) {
-          console.log('[STT] Global STT -> updating session', newState);
+          logger.log(
+            LogSource.Internals,
+            'TRANSCRIPT',
+            `${TRANSCRIPT_JOURNEY} STT global state selected update operation`,
+            {
+              stage: 'global_state_operation',
+              outcome: 'started',
+              stateOrigin: isLocal ? 'local' : 'remote',
+            },
+          );
           const result = await updateSTTBotSession(
             {
               source: [newState.globalSpokenLanguage],
@@ -1061,7 +1212,16 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
           }
           return true;
         } else if (isStopOperation) {
-          console.log('[STT] Global STT -> stopping session', newState);
+          logger.log(
+            LogSource.Internals,
+            'TRANSCRIPT',
+            `${TRANSCRIPT_JOURNEY} STT global state selected stop operation`,
+            {
+              stage: 'global_state_operation',
+              outcome: 'started',
+              stateOrigin: isLocal ? 'local' : 'remote',
+            },
+          );
           await stopSTTBotSession();
           sttStartGuardRef.current = false;
           return true;
@@ -1074,8 +1234,8 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
         logger.error(
           LogSource.Internals,
           'STT',
-          'Error handling STT_GLOBAL_STATE event',
-          error,
+          `${TRANSCRIPT_JOURNEY} error handling STT_GLOBAL_STATE event`,
+          error ?? null,
         );
         return false;
       }
@@ -1087,7 +1247,16 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
   React.useEffect(() => {
     const handleGlobalSTTChange = async (evt: any) => {
       const {payload} = evt || {};
-      console.log('[STT] STT_GLOBAL_STATE event received: ', evt);
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} STT_GLOBAL_STATE event received`,
+        {
+          stage: 'global_state_event',
+          outcome: 'received',
+          payloadPresent: typeof payload === 'string' && payload.length > 0,
+        },
+      );
       let newState: GlobalSttState;
       try {
         newState = JSON.parse(payload);
@@ -1095,8 +1264,8 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
         logger.error(
           LogSource.Internals,
           'STT',
-          'Failed to parse STT_GLOBAL_STATE event payload',
-          error,
+          `${TRANSCRIPT_JOURNEY} failed to parse STT_GLOBAL_STATE event payload`,
+          error ?? null,
         );
         return;
       }

package/template/src/subComponents/caption/useSTTAPI.tsx

@@ -7,6 +7,7 @@ import {logger, LogSource} from '../../logger/AppBuilderLogger';
 import getUniqueID from '../../utils/getUniqueID';
 import {buildSTTRequestBody, type STTMethod} from './sttRequestBody';
 import {ensureSTTSessionId} from './sttSessionId';
+import {TRANSCRIPT_JOURNEY} from './transcriptJourney';
 
 export interface STTAPIResponse {
   success: boolean;
@@ -99,12 +100,12 @@ const useSTTAPI = (): IuseSTTAPI => {
       });
 
       console.log(
-        `[STT_BOT_SUBSCRIPTION] ${method.toUpperCase()} - Bot UID: ${botUid} will subscribe to User UID: ${ownerUid}`,
+        `${TRANSCRIPT_JOURNEY} [STT_BOT_SUBSCRIPTION] ${method.toUpperCase()} - Bot UID: ${botUid} will subscribe to User UID: ${ownerUid}`,
         {
           method,
           botUid,
           ownerUid,
-          translationConfig,
+          translationConfig: translationConfig ?? null,
         },
       );
       const response = await fetch(`${STT_API_URL}/${method}`, {
@@ -146,10 +147,10 @@ const useSTTAPI = (): IuseSTTAPI => {
         logger.error(
           LogSource.NetworkRest,
           'stt',
-          `STT API Failure - Called ${method}`,
-          errorPayload,
+          `${TRANSCRIPT_JOURNEY} STT API Failure - Called ${method}`,
+          errorPayload ?? {message},
           {
-            responseData: res,
+            responseData: res ?? null,
             httpStatus,
             requestId,
             startReqTs,
@@ -172,9 +173,9 @@ const useSTTAPI = (): IuseSTTAPI => {
       logger.log(
         LogSource.NetworkRest,
         'stt',
-        `STT API Success - Called ${method}`,
+        `${TRANSCRIPT_JOURNEY} STT API Success - Called ${method}`,
         {
-          responseData: res,
+          responseData: res ?? null,
           httpStatus,
           requestId,
           startReqTs,
@@ -194,8 +195,8 @@ const useSTTAPI = (): IuseSTTAPI => {
       logger.error(
         LogSource.NetworkRest,
         'stt',
-        `STT API Failure - Called ${method}`,
-        error,
+        `${TRANSCRIPT_JOURNEY} STT API Failure - Called ${method}`,
+        error ?? null,
         {
           requestId,
           startReqTs,
@@ -235,14 +236,14 @@ const useSTTAPI = (): IuseSTTAPI => {
       logger.log(
         LogSource.NetworkRest,
         'stt',
-        'Retrying STT start after transient failure',
+        `${TRANSCRIPT_JOURNEY} Retrying STT start after transient failure`,
         {
           attempt,
           maxAttempts: STT_START_MAX_ATTEMPTS,
           retryDelayMs,
           botUid,
-          httpStatus: result.httpStatus,
-          errorCode: result.error?.code,
+          httpStatus: result.httpStatus ?? null,
+          errorCode: result.error?.code ?? null,
         },
       );
       await wait(retryDelayMs);