mediasfu-reactjs
Version:
MediaSFU Prebuilt ReactJS SDK - Compatible with React 18 & 19, TypeScript & JavaScript
382 lines • 14.7 kB
TypeScript
/**
* Handler for translation-related socket events.
*
* Listens for:
* - translation:roomConfig - Room-level translation configuration
* - translation:configUpdated - Host updated room config
* - translation:languageSet - Confirmation of spoken language set
* - translation:subscribed - Confirmation of translation subscription
* - translation:unsubscribed - Confirmation of translation unsubscription
* - translation:producerReady - Translation producer is available for consumption
* - translation:producerClosed - Translation producer was closed
* - translation:channelsAvailable - Channels available from a speaker
* - translation:memberState - Another member's translation state
* - translation:error - Translation operation error
*/
import { ShowAlert } from '../../@types/types';
export type LanguageMode = 'allowlist' | 'blocklist' | 'any';
/**
* Voice config for per-language credential/param overrides
*/
export interface TranslationVoiceConfig {
sttNickName?: string;
llmNickName?: string;
ttsNickName?: string;
sttParams?: Record<string, string | number | boolean>;
llmParams?: Record<string, string | number | boolean>;
ttsParams?: Record<string, string | number | boolean>;
}
/**
* Language entry with optional per-language voice config
*/
export interface LanguageEntry {
code: string;
nickname?: string;
voiceConfig?: TranslationVoiceConfig;
}
export interface TranslationRoomConfig {
supportTranslation: boolean;
spokenLanguageMode: LanguageMode;
allowedSpokenLanguages?: LanguageEntry[];
blockedSpokenLanguages?: string[];
listenLanguageMode: LanguageMode;
allowedListenLanguages?: LanguageEntry[];
blockedListenLanguages?: string[];
maxActiveChannelsPerSpeaker: number;
autoDetectSpokenLanguage: boolean;
allowSpokenLanguageChange?: boolean;
allowListenLanguageChange?: boolean;
translationVoiceConfig?: TranslationVoiceConfig | null;
providerGroups?: {
groupA?: {
languages: string[];
sttNickName?: string;
llmNickName?: string;
ttsNickName?: string;
};
groupB?: {
languages: string[];
sttNickName?: string;
llmNickName?: string;
ttsNickName?: string;
};
default?: {
sttNickName?: string;
llmNickName?: string;
ttsNickName?: string;
};
} | null;
}
export interface TranslationRoomConfigData {
config: TranslationRoomConfig;
}
export interface TranslationConfigUpdatedData {
config: TranslationRoomConfig;
}
export interface TranslationLanguageSetData {
success: boolean;
language: string;
enabled: boolean;
error?: string;
}
export interface TranslationSubscribedData {
speakerId: string;
speakerName?: string;
language: string;
channelCreated: boolean;
producerId?: string;
originalProducerId?: string;
}
export interface TranslationUnsubscribedData {
speakerId: string;
language: string;
channelClosed: boolean;
}
export interface TranslationProducerReadyData {
speakerId: string;
speakerName?: string;
language: string;
producerId: string;
originalProducerId: string;
}
export interface TranslationProducerClosedData {
speakerId: string;
language: string;
producerId: string;
reason?: string;
}
export interface TranslationChannelsAvailableData {
speakerId: string;
speakerName?: string;
languages: string[];
originalProducerId: string;
}
export interface TranslationMemberStateData {
memberId: string;
memberName?: string;
state: {
speaking?: {
enabled: boolean;
inputLanguage: string;
originalProducerId: string;
};
listening?: {
[speakerId: string]: {
language: string;
producerId: string | null;
};
};
};
}
export interface TranslationErrorData {
error: string;
code?: string;
details?: unknown;
/** Available channels when max_channels error occurs */
availableChannels?: string[];
/** Maximum channels allowed for a speaker */
maxChannels?: number;
/** User-friendly message from backend */
message?: string;
}
/**
* Data received when a speaker changes their output language.
* This is automatic - consumers don't choose, the speaker decides.
* When outputLanguage is set, consumers should:
* 1. Pause their consumer of the speaker's original audio
* 2. Wait for translation producer to arrive via new-pipe-producer
* 3. Consume the translation producer instead
*/
export interface TranslationSpeakerOutputChangedData {
speakerId: string;
speakerName: string;
inputLanguage: string;
outputLanguage: string | null;
originalProducerId: string;
enabled: boolean;
}
export interface TranslationRoomConfigOptions {
data: TranslationRoomConfigData;
updateTranslationConfig?: (config: TranslationRoomConfig) => void;
updateTranslationSupported?: (supported: boolean) => void;
}
export interface TranslationConfigUpdatedOptions {
data: TranslationConfigUpdatedData;
updateTranslationConfig?: (config: TranslationRoomConfig) => void;
showAlert?: ShowAlert;
}
export interface TranslationLanguageSetOptions {
data: TranslationLanguageSetData;
updateMySpokenLanguage?: (lang: string) => void;
updateMySpokenLanguageEnabled?: (enabled: boolean) => void;
showAlert?: ShowAlert;
}
export interface TranslationSubscribedOptions {
data: TranslationSubscribedData;
updateListenPreferences?: (updater: (prev: Map<string, string>) => Map<string, string>) => void;
updateTranslationProducerMap?: (updater: (prev: TranslationProducerMap) => TranslationProducerMap) => void;
startConsumingTranslation?: (producerId: string, speakerId: string, language: string) => Promise<void>;
showAlert?: ShowAlert;
}
export interface TranslationUnsubscribedOptions {
data: TranslationUnsubscribedData;
updateListenPreferences?: (updater: (prev: Map<string, string>) => Map<string, string>) => void;
stopConsumingTranslation?: (speakerId: string, language: string) => Promise<void>;
}
export interface TranslationProducerReadyOptions {
data: TranslationProducerReadyData;
updateTranslationProducerMap?: (updater: (prev: TranslationProducerMap) => TranslationProducerMap) => void;
startConsumingTranslation?: (producerId: string, speakerId: string, language: string, originalProducerId: string) => Promise<void>;
pauseOriginalProducer?: (originalProducerId: string) => Promise<void>;
showAlert?: ShowAlert;
}
export interface TranslationProducerClosedOptions {
data: TranslationProducerClosedData;
updateTranslationProducerMap?: (updater: (prev: TranslationProducerMap) => TranslationProducerMap) => void;
stopConsumingTranslation?: (producerId: string) => Promise<void>;
resumeOriginalProducer?: (speakerId: string) => Promise<void>;
showAlert?: ShowAlert;
}
export interface TranslationChannelsAvailableOptions {
data: TranslationChannelsAvailableData;
updateAvailableTranslationChannels?: (speakerId: string, languages: string[], originalProducerId: string) => void;
myDefaultListenLanguage?: string | null;
socket?: any;
roomName?: string;
}
export interface TranslationMemberStateOptions {
data: TranslationMemberStateData;
updateParticipantTranslationState?: (memberId: string, state: TranslationMemberStateData['state']) => void;
}
export interface TranslationErrorOptions {
data: TranslationErrorData;
showAlert?: ShowAlert;
}
/**
* Options for handling speaker output language change
* This is automatic - when a speaker sets an output language, ALL consumers
* must pause original audio and consume translation instead
*/
export interface TranslationSpeakerOutputChangedOptions {
data: TranslationSpeakerOutputChangedData;
pauseOriginalProducer?: (originalProducerId: string, speakerId: string) => Promise<void>;
resumeOriginalProducer?: (originalProducerId: string, speakerId: string) => Promise<void>;
stopConsumingTranslationForSpeaker?: (speakerId: string) => Promise<void>;
updateSpeakerTranslationState?: (speakerId: string, outputLanguage: string | null, originalProducerId: string) => void;
showAlert?: ShowAlert;
listenerOverride?: {
speakerId: string;
wantOriginal: boolean;
preferredLanguage?: string;
} | null;
}
export interface TranslationTranscriptData {
speakerId: string;
speakerName: string;
language: string;
originalText: string;
translatedText: string;
sourceLang: string;
detectedLanguage?: string | null;
timestamp: number;
}
export interface TranslationTranscriptOptions {
data: TranslationTranscriptData;
updateTranscripts?: (updater: (prev: TranslationTranscriptData[]) => TranslationTranscriptData[]) => void;
onTranscriptReceived?: (transcript: TranslationTranscriptData) => void;
maxTranscripts?: number;
}
export interface TranslationProducerMap {
[originalProducerId: string]: {
[languageCode: string]: string;
};
}
export type TranslationRoomConfigType = (options: TranslationRoomConfigOptions) => Promise<void>;
export type TranslationConfigUpdatedType = (options: TranslationConfigUpdatedOptions) => Promise<void>;
export type TranslationLanguageSetType = (options: TranslationLanguageSetOptions) => Promise<void>;
export type TranslationSubscribedType = (options: TranslationSubscribedOptions) => Promise<void>;
export type TranslationUnsubscribedType = (options: TranslationUnsubscribedOptions) => Promise<void>;
export type TranslationProducerReadyType = (options: TranslationProducerReadyOptions) => Promise<void>;
export type TranslationProducerClosedType = (options: TranslationProducerClosedOptions) => Promise<void>;
export type TranslationChannelsAvailableType = (options: TranslationChannelsAvailableOptions) => Promise<void>;
export type TranslationMemberStateType = (options: TranslationMemberStateOptions) => Promise<void>;
export type TranslationErrorType = (options: TranslationErrorOptions) => Promise<void>;
export type TranslationTranscriptType = (options: TranslationTranscriptOptions) => Promise<void>;
export type TranslationSpeakerOutputChangedType = (options: TranslationSpeakerOutputChangedOptions) => Promise<void>;
/**
* Handles the translation:roomConfig socket event.
* Called when joining a room to receive room-level translation configuration.
*
* @example
* ```typescript
* socket.on("translation:roomConfig", async (data: TranslationRoomConfigData) => {
* await translationRoomConfig({
* data,
* updateTranslationConfig,
* updateTranslationSupported,
* });
* });
* ```
*/
export declare const translationRoomConfig: TranslationRoomConfigType;
/**
* Handles the translation:configUpdated socket event.
* Called when the host changes room translation settings.
*/
export declare const translationConfigUpdated: TranslationConfigUpdatedType;
/**
* Handles the translation:languageSet socket event.
* Called when the user's spoken language is confirmed.
*/
export declare const translationLanguageSet: TranslationLanguageSetType;
/**
* Handles the translation:subscribed socket event.
* Called when successfully subscribed to a translation channel.
*/
export declare const translationSubscribed: TranslationSubscribedType;
/**
* Handles the translation:unsubscribed socket event.
* Called when unsubscribed from a translation channel.
*/
export declare const translationUnsubscribed: TranslationUnsubscribedType;
/**
* Handles the translation:producerReady socket event.
* Called when a translation producer is ready for consumption.
*
* NOTE: This event comes from the PRODUCING socket with the original producer ID.
* The actual consumption happens via `new-pipe-producer` from CONSUMING sockets
* with the piped producer ID. This handler only updates state/maps.
*/
export declare const translationProducerReady: TranslationProducerReadyType;
/**
* Handles the translation:producerClosed socket event.
* Called when a translation producer is closed.
*/
export declare const translationProducerClosed: TranslationProducerClosedType;
/**
* Handles the translation:channelsAvailable socket event.
* Called when a speaker has translation channels available.
*/
export declare const translationChannelsAvailable: TranslationChannelsAvailableType;
/**
* Handles the translation:memberState socket event.
* Called when another member's translation state changes.
*/
export declare const translationMemberState: TranslationMemberStateType;
/**
* Handles the translation:error socket event.
* Called when a translation operation fails.
*/
export declare const translationError: TranslationErrorType;
/**
* Handles the translation:transcript socket event.
* Called when a translation transcript (text) is available for display.
*
* Use this for:
* - Live captions/subtitles
* - Transcript panel
* - Accessibility features
*
* @example
* ```typescript
* socket.on("translation:transcript", async (data: TranslationTranscriptData) => {
* await translationTranscript({
* data,
* updateTranscripts: setTranscripts,
* onTranscriptReceived: (transcript) => {
* console.log(`${transcript.speakerName}: ${transcript.translatedText}`);
* },
* });
* });
* ```
*/
export declare const translationTranscript: TranslationTranscriptType;
/**
* Handles the `translation:speakerOutputChanged` event.
*
* This is emitted when a speaker changes their output language.
* When a speaker sets an output language (different from their spoken language),
* ALL consumers must automatically:
* 1. Pause their consumer of the speaker's original audio
* 2. Wait for translation producer to arrive via new-pipe-producer
* 3. Consume the translation producer instead
*
* This is NOT optional for consumers - the speaker decides what everyone hears.
*
* @example
* ```typescript
* socket.on("translation:speakerOutputChanged", async (data) => {
* await translationSpeakerOutputChanged({
* data,
* pauseOriginalProducer: async (producerId, speakerId) => {
* // Pause consumer for this producer
* },
* resumeOriginalProducer: async (producerId, speakerId) => {
* // Resume consumer for this producer
* },
* });
* });
* ```
*/
export declare const translationSpeakerOutputChanged: TranslationSpeakerOutputChangedType;
//# sourceMappingURL=translationReceiveMethods.d.ts.map