tencent cloud

Tencent Real-Time Communication

소식 및 공지 사항
제품 업데이트
Tencent Cloud 오디오/비디오 단말 SDK 재생 업그레이드 및 권한 부여 인증 추가
TRTC 월간 구독 패키지 출시 관련 안내
제품 소개
제품 개요
기본 개념
제품 기능
제품 장점
응용 시나리오
성능 데이터
구매 가이드
Billing Overview
무료 시간 안내
Monthly subscription
Pay-as-you-go
TRTC Overdue and Suspension Policy
과금 FAQ
Refund Instructions
신규 사용자 가이드
Demo 체험
Call
개요(TUICallKit)
Activate the Service
Run Demo
빠른 통합(TUICallKit)
오프라인 푸시
Conversational Chat
온클라우드 녹화(TUICallKit)
AI Noise Reduction
UI 사용자 정의
Calls integration to Chat
Additional Features
No UI Integration
Server APIs
Client APIs
Solution
ErrorCode
릴리스 노트
FAQs
라이브 스트리밍
Billing of Video Live Component
Overview
Activating the Service (TUILiveKit)
Demo 실행
No UI Integration
UI Customization
Live Broadcast Monitoring
Video Live Streaming
Voice Chat Room
Advanced Features
Client APIs
Server APIs
Error Codes
Release Notes
FAQs
RTC Engine
Activate Service
SDK 다운로드
API 코드 예시
Usage Guidelines
API 클라이언트 API
고급 기능
RTC RESTFUL API
History
Introduction
API Category
Room Management APIs
Stream mixing and relay APIs
On-cloud recording APIs
Data Monitoring APIs
Pull stream Relay Related interface
Web Record APIs
AI Service APIs
Cloud Slicing APIs
Cloud Moderation APIs
Making API Requests
Call Quality Monitoring APIs
Usage Statistics APIs
Data Types
Appendix
Error Codes
콘솔 가이드
애플리케이션 관리
사용량 통계
모니터링 대시보드
개발 보조
Solution
Real-Time Chorus
FAQs
과금 개요
기능 관련
UserSig 관련
방화벽 제한 처리
설치 패키지 용량 축소 관련 질문
Andriod 및 iOS 관련
Web 관련
Flutter 관련
Electron 관련
TRTCCalling Web 관련
멀티미디어 품질 관련
기타 질문
Protocols and Policies
컴플라이언스 인증
보안 백서
정보 보안에 관한 참고 사항
Service Level Agreement
Apple Privacy Policy: PrivacyInfo.xcprivacy
TRTC 정책
개인 정보 보호 정책
데이터 처리 및 보안 계약
용어집
문서Tencent Real-Time Communication라이브 스트리밍No UI IntegrationVoice Chat RoomSound EffectsSound Effects (Flutter)

Sound Effects (Flutter)

PDF
포커스 모드
폰트 크기
마지막 업데이트 시간: 2026-02-27 20:58:07
This guide shows you how to use the AudioEffectStore and DeviceStore modules from the AtomicXCore framework to quickly add audio effect controls to your live streaming app. With these modules, you can implement features like microphone volume adjustment, in-ear monitoring, and a range of engaging voice changer and reverb effects.


Core Features

By integrating AudioEffectStore and DeviceStore, you can enable the following features in your live streaming app:
Microphone Volume Control: Adjust the local capture volume to control how loud the host sounds to the audience.
In-Ear Monitor: Let hosts or guests hear their own voice in real time through headphones for monitoring and pronunciation correction.
Voice Changer Effects: Provide multiple voice changer options, such as Child, Girl, Uncle, and more.
Reverb Effects: Simulate various acoustic environments, including KTV, metallic, deep, bright, and others.

Concept Overview

Core Concept
Type
Key Responsibilities & Description
class
Tracks the current state of the audio effects module, typically for UI rendering. Includes voice changer status, reverb status, in-ear monitor enabled status, and in-ear monitor volume. All properties are ValueListenable and support state change subscriptions.
class
Singleton data manager for the audio effects module. Use this to call audio effect APIs. After you call an API, the relevant audioEffectState property updates automatically; subscribe to this reactive state for real-time updates.
class
Tracks the current state of the device module, typically for UI rendering. Key properties include camera and microphone device status, capture volume, and more. All properties are ValueListenable and support state change subscriptions.
class
Singleton data manager for the device module. Use this to control camera and microphone APIs. After you call an API, the relevant state property updates automatically; subscribe to this reactive state for real-time updates.

Implementation Steps

Step 1: Integrate the Component

Live streaming: Refer to Quick Integration to integrate AtomicXCore and complete service access.
Voice chat room: Refer to Quick Integration to integrate AtomicXCore and complete service access.

Step 2: Obtain a Store Instance

Both AudioEffectStore and DeviceStore are singletons. You can access their instances anywhere in your project using the shared property. For a full implementation example, refer to the audio_effect_panel_widget.dart file in the TUILiveKit open-source UI demo project.
import 'package:flutter/material.dart';
import 'package:atomic_x_core/atomicxcore.dart';

class _AudioEffectPanelWidgetState {
  final _audioEffectStore = AudioEffectStore.shared;
  final _deviceStore = DeviceStore.shared;
}

Step 3: Implement the In-Ear Monitor

In-ear monitor allows users to hear their own microphone input in real time. You can manage this feature using the APIs described below.
Note:
The in-ear monitoring feature typically needs to connect to headphones to work properly.
1. Enable/Disable Ear Monitoring: Use a Switch widget to enable or disable in-ear monitor.
2. Set the Volume of IEMs: Use a Slider widget to set the volume. Map the slider value to the volume parameter and call setVoiceEarMonitorVolume(volume). The valid range is [0, 150], so map your UI control's value (e.g., slider 0.0 - 1.0) to 0 - 150.
3. Listen for Status Updates to Update UI: Listen for real-time in-ear monitor state changes to update your UI accordingly.

Sample Code

import 'package:flutter/material.dart';
import 'package:atomic_x_core/atomicxcore.dart';

/// Ear Monitoring Control Component
class EarMonitorWidget extends StatelessWidget {
  const EarMonitorWidget({super.key});

  @override
  Widget build(BuildContext context) {
    final audioEffectStore = AudioEffectStore.shared;

    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        // 1. Toggle ear monitoring
        ValueListenableBuilder<bool>(
          valueListenable: audioEffectStore.audioEffectState.isEarMonitorOpened,
          builder: (context, isOpened, child) {
            return SwitchListTile(
              title: const Text('Ear Monitoring'),
              subtitle: const Text('Insert a headset')
              value: isOpened,
              onChanged: (value) {
                audioEffectStore.setVoiceEarMonitorEnable(value);
              },
            );
          },
        ),
        // 2. Adjust ear return volume
        ValueListenableBuilder<int>(
          valueListenable: audioEffectStore.audioEffectState.earMonitorVolume,
          builder: (context, volume, child) {
            return ListTile(
              title: const Text('Ear Monitoring Volume'),
              subtitle: Slider(
                value: volume.toDouble(),
                min: 0,
                max: 150,
                divisions: 150,
                onChanged: (value) {
                  audioEffectStore.setVoiceEarMonitorVolume(value.toInt());
                },
              ),
              trailing: Text('$volume'),
            );
          },
        ),
      ],
    );
  }
}

SetVoiceEarMonitorEnable API Parameters

Parameter Name
Type
Description
enable
bool
Enable in-ear monitor:
true: Enable.
false: Disable.

SetVoiceEarMonitorVolume API Parameters

Parameter Name
Type
Description
volume
int
Ear return volume.
Value ranges from 0 to 150.
Default value: 100.

Step 4: Adjust Microphone Volume

To control the host's microphone capture volume, call DeviceStore.setCaptureVolume(volume) with your desired value.
1. Set Capturing Volume: You can use the Slider control to drag the slider left and right to adjust volume, and map the Slider value to the volume value before calling setCaptureVolume(volume). Please note, this API accepts a parameter range of [0, 150], so you need to map the UI control value (such as the Slider's 0.0 - 1.0) to the 0 - 150 range.
2. Subscribe to State Updates: Listen for real-time capture volume changes to update your UI.

Sample Code

import 'package:flutter/material.dart';
import 'package:atomic_x_core/atomicxcore.dart';

/// Voice Volume Control Component
class CaptureVolumeWidget extends StatelessWidget {
  const CaptureVolumeWidget({super.key});

  @override
  Widget build(BuildContext context) {
    final deviceStore = DeviceStore.shared;

    return ValueListenableBuilder<int>(
      valueListenable: deviceStore.state.captureVolume,
      builder: (context, volume, child) {
        return ListTile(
          title: const Text('Voice Volume'),
          subtitle: Slider(
            value: volume.toDouble(),
            min: 0,
            max: 150,
            divisions: 150,
            onChanged: (value) {
              deviceStore.setCaptureVolume(value.toInt());
            },
          ),
          trailing: Text('$volume'),
        );
      },
    );
  }
}

SetCaptureVolume API Parameters

Parameter Name
Type
Description
volume
int
Capture volume size.
Value ranges from 0 to 150.
Default value: 100.

Step 5: Apply Voice Changer Effects

To change the host's voice, call setAudioChangerType(type) and pass the desired enum value.

Sample Code

import 'package:flutter/material.dart';
import 'package:atomic_x_core/atomicxcore.dart';

/// Voice changing effect selection component
class VoiceChangerWidget extends StatelessWidget {
  const VoiceChangerWidget({super.key});

  @override
  Widget build(BuildContext context) {
    final audioEffectStore = AudioEffectStore.shared;

    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        const Padding(
          padding: EdgeInsets.all(16),
          child: Text('Voice-changing effect', style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold)),
        ),
        ValueListenableBuilder<AudioChangerType>(
          valueListenable: audioEffectStore.audioEffectState.audioChangerType,
          builder: (context, changerType, child) {
            return Padding(
              padding: const EdgeInsets.symmetric(horizontal: 16),
              child: Wrap(
                spacing: 8,
                runSpacing: 8,
                children: AudioChangerType.values.map((type) {
                  return ChoiceChip(
                    label: Text(_getChangerTypeName(type)),
                    selected: changerType == type,
                    onSelected: (selected) {
                      if (selected) {
                        audioEffectStore.setAudioChangerType(type);
                      }
                    },
                  );
                }).toList(),
              ),
            );
          },
        ),
      ],
    );
  }

  String _getChangerTypeName(AudioChangerType type) {
    switch (type) {
      case AudioChangerType.none:
        return 'Disable';
      case AudioChangerType.child:
        return 'mischievous child';
      case AudioChangerType.girl:
        return 'loli';
      case AudioChangerType.uncle:
        return 'uncle';
      case AudioChangerType.ethereal:
        return 'ethereal';
    }
  }
}

SetAudioChangerType API Parameters

Parameter Name
Type
Description
type
AudioChangerType
Voice-changing effects enumeration.

Step 6: Apply Reverb Effects

To add reverb effects to the host's voice, call setAudioReverbType(type) and pass the desired enum value.

Sample Code

import 'package:flutter/material.dart';
import 'package:atomic_x_core/atomicxcore.dart';

/// Reverb effect selection component
class ReverbWidget extends StatelessWidget {
  const ReverbWidget({super.key});

  @override
  Widget build(BuildContext context) {
    final audioEffectStore = AudioEffectStore.shared;

    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        const Padding(
          padding: EdgeInsets.all(16),
          child: Text('Reverb effect', style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold)),
        ),
        ValueListenableBuilder<AudioReverbType>(
          valueListenable: audioEffectStore.audioEffectState.audioReverbType,
          builder: (context, reverbType, child) {
            return Padding(
              padding: const EdgeInsets.symmetric(horizontal: 16),
              child: Wrap(
                spacing: 8,
                runSpacing: 8,
                children: AudioReverbType.values.map((type) {
                  return ChoiceChip(
                    label: Text(_getReverbTypeName(type)),
                    selected: reverbType == type,
                    onSelected: (selected) {
                      if (selected) {
                        audioEffectStore.setAudioReverbType(type);
                      }
                    },
                  );
                }).toList(),
              ),
            );
          },
        ),
      ],
    );
  }

  String _getReverbTypeName(AudioReverbType type) {
    switch (type) {
      case AudioReverbType.none:
        return 'Disable';
      case AudioReverbType.ktv:
        return 'KTV';
      case AudioReverbType.room:
        return 'Small room';
      case AudioReverbType.hall:
        return 'Great hall';
      case AudioReverbType.deep:
        return 'deep';
      case AudioReverbType.loud:
        return 'resonant';
      case AudioReverbType.metallic:
        return 'metallic sound';
      case AudioReverbType.magnetic:
        return 'magnetic';
      case AudioReverbType.recordingStudio:
        return 'studio';
    }
  }
}

SetAudioReverbType API Parameters

Parameter Name
Type
Description
type
AudioReverbType
Reverb effects enumeration.

Step 7: Reset Sound Effect Settings

Important:
AudioEffectStore and DeviceStore are singletons, so audio effects and device settings take effect globally. If you do not want the settings of the current live streaming room to affect other live streaming rooms created later, you need to reset the audio effects and device settings when the current live streaming room ends.
You may need to reset sound effect settings in the following two scenarios:
1. When the current live streaming room ends, call the store's reset() method to reset sound effects.
2. When you need to reset all devices and sound effect settings, call the store's reset() method to reset sound effects.
import 'package:flutter/material.dart';
import 'package:atomic_x_core/atomicxcore.dart';

/// Sound effect reset component
class AudioEffectResetWidget extends StatelessWidget {
  const AudioEffectResetWidget({super.key});

  void _resetAudioEffect() {
    AudioEffectStore.shared.reset();
    DeviceStore.shared.reset();
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: _resetAudioEffect,
      child: const Text('Reset sound effect settings'),
    );
  }
}

Complete Sample Code

import 'package:flutter/material.dart';
import 'package:atomic_x_core/atomicxcore.dart';

/// Sound effect settings page
class AudioEffectPage extends StatelessWidget {
  const AudioEffectPage({super.key});

  @override
  Widget build(BuildContext context) {
    final audioEffectStore = AudioEffectStore.shared;
    final deviceStore = DeviceStore.shared;

    return Scaffold(
      appBar: AppBar(title: const Text('Sound effect settings')),
      body: ListView(
        children: [
          // Voice volume
          const Padding(
            padding: EdgeInsets.all(16),
            child: Text('Voice volume', style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold)),
          ),
          ValueListenableBuilder<int>(
            valueListenable: deviceStore.state.captureVolume,
            builder: (context, volume, child) {
              return ListTile(
                title: const Text('Capture Volume'),
                subtitle: Slider(
                  value: volume.toDouble(),
                  min: 0,
                  max: 150,
                  divisions: 150,
                  onChanged: (value) {
                    deviceStore.setCaptureVolume(value.toInt());
                  },
                ),
                trailing: Text('$volume'),
              );
            },
          ),
          const Divider(),

          // Ear return settings
          const Padding(
            padding: EdgeInsets.all(16),
            child: Text('Ear monitoring', style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold)),
          ),
          ValueListenableBuilder<bool>(
            valueListenable: audioEffectStore.audioEffectState.isEarMonitorOpened,
            builder: (context, isOpened, child) {
              return SwitchListTile(
                title: const Text('Enable Ear Monitoring'),
                subtitle: const Text('Insert a headset')
                value: isOpened,
                onChanged: (value) {
                  audioEffectStore.setVoiceEarMonitorEnable(value);
                },
              );
            },
          ),
          ValueListenableBuilder<int>(
            valueListenable: audioEffectStore.audioEffectState.earMonitorVolume,
            builder: (context, volume, child) {
              return ListTile(
                title: const Text('Ear Monitoring Volume'),
                subtitle: Slider(
                  value: volume.toDouble(),
                  min: 0,
                  max: 150,
                  divisions: 150,
                  onChanged: (value) {
                    audioEffectStore.setVoiceEarMonitorVolume(value.toInt());
                  },
                ),
                trailing: Text('$volume'),
              );
            },
          ),
          const Divider(),

          // Voice changing settings
          const Padding(
            padding: EdgeInsets.all(16),
            child: Text('Voice-changing', style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold)),
          ),
          ValueListenableBuilder<AudioChangerType>(
            valueListenable: audioEffectStore.audioEffectState.audioChangerType,
            builder: (context, changerType, child) {
              return Padding(
                padding: const EdgeInsets.symmetric(horizontal: 16),
                child: Wrap(
                  spacing: 8,
                  runSpacing: 8,
                  children: AudioChangerType.values.map((type) {
                    return ChoiceChip(
                      label: Text(_getChangerTypeName(type)),
                      selected: changerType == type,
                      onSelected: (selected) {
                        if (selected) {
                          audioEffectStore.setAudioChangerType(type);
                        }
                      },
                    );
                  }).toList(),
                ),
              );
            },
          ),
          const SizedBox(height: 16),
          const Divider(),

          // Reverb settings
          const Padding(
            padding: EdgeInsets.all(16),
            child: Text('Reverb', style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold)),
          ),
          ValueListenableBuilder<AudioReverbType>(
            valueListenable: audioEffectStore.audioEffectState.audioReverbType,
            builder: (context, reverbType, child) {
              return Padding(
                padding: const EdgeInsets.symmetric(horizontal: 16),
                child: Wrap(
                  spacing: 8,
                  runSpacing: 8,
                  children: AudioReverbType.values.map((type) {
                    return ChoiceChip(
                      label: Text(_getReverbTypeName(type)),
                      selected: reverbType == type,
                      onSelected: (selected) {
                        if (selected) {
                          audioEffectStore.setAudioReverbType(type);
                        }
                      },
                    );
                  }).toList(),
                ),
              );
            },
          ),
          const SizedBox(height: 24),

          // reset button
          Padding(
            padding: const EdgeInsets.all(16),
            child: ElevatedButton(
              onPressed: () {
                audioEffectStore.reset();
                deviceStore.reset();
              },
              child: const Text('Reset sound effect settings'),
            ),
          ),
        ],
      ),
    );
  }

  String _getChangerTypeName(AudioChangerType type) {
    switch (type) {
      case AudioChangerType.none:
        return 'Disable';
      case AudioChangerType.child:
        return 'mischievous child';
      case AudioChangerType.girl:
        return 'loli';
      case AudioChangerType.uncle:
        return 'uncle';
      case AudioChangerType.ethereal:
        return 'ethereal';
    }
  }

  String _getReverbTypeName(AudioReverbType type) {
    switch (type) {
      case AudioReverbType.none:
        return 'Disable';
      case AudioReverbType.ktv:
        return 'KTV';
      case AudioReverbType.room:
        return 'Small room';
      case AudioReverbType.hall:
        return 'Great hall';
      case AudioReverbType.deep:
        return 'deep';
      case AudioReverbType.loud:
        return 'resonant';
      case AudioReverbType.metallic:
        return 'metallic sound';
      case AudioReverbType.magnetic:
        return 'magnetic';
      case AudioReverbType.recordingStudio:
        return 'studio';
    }
  }
}

API documentation

For detailed information about all public interfaces and attributes of AudioEffectStore, DeviceStore and its related classes, see the official API documentation of the AtomicXCore framework.
Store/Component
Feature Description
API Reference
AudioEffectStore
Audio effect management: Perform audio effect settings and obtain real-time audio effect status.
API documentation
DeviceStore
Device management: perform camera and microphone operations and obtain real-time device status.
API documentation

FAQs

Are there any restrictions on when to call audio effect and device APIs?

No, there are no restrictions. Settings in AudioEffectStore and DeviceStore are global. You can call related APIs (such as setting voice changer, reverb, or in-ear monitor) at any time before or after joining a live room. Changes take effect immediately and persist.

What is the difference between "Microphone Volume" and "In-Ear Monitor Volume"?

This is a common source of confusion. The differences are:
Microphone Volume (Capture Volume): Set via DeviceStore.shared.setCaptureVolume(). Controls how loud the host sounds to the audience.
In-Ear Monitor Volume (Ear Monitor Volume): Set via AudioEffectStore.shared.setVoiceEarMonitorVolume(). Controls only how loud the host hears themselves in their headphones and does not affect the audience.

Why does a newly created live room already have audio effects, or the volume is unexpectedly high or low?

Because AudioEffectStore and DeviceStore are singletons, audio effect and device settings are global. This usually happens if you previously set audio effects and didn't reset them. Be sure to call reset() when appropriate.

Why can't I hear myself after enabling "In-Ear Monitor"?

Check the following:
1. Are headphones connected? In-ear monitor usually requires headphones. Make sure wired or Bluetooth headphones are connected.
2. Is the volume set to 0? Verify that "In-Ear Monitor Volume" is not set to 0.
3. Is the microphone enabled? Ensure that the microphone in DeviceStore is enabled (i.e., openLocalMicrophone() has been called).

Can I use voice changer and reverb effects at the same time?

Yes. AudioChangerType and AudioReverbType can be used together. For example, you can apply both AudioChangerType.girl and AudioReverbType.ktv simultaneously.
이전 주제: Sound Effects (iOS)다음 주제: Live Stream Video Component（Web Desktop Browser）

도움말 및 지원

문제 해결에 도움이 되었나요?

피드백