tencent cloud

Mobile Live Video Broadcasting

DocumentaçãoMobile Live Video BroadcastingClient APIsiOSDeviceStore

DeviceStore

Baixar
Modo Foco
Tamanho da Fonte
Última atualização: 2026-11-02 17:31:52

Introduction

DeviceStore provides a comprehensive set of APIs to manage audio and video devices, including microphone, camera and screen sharing features.
Notice:
Use shared singleton to get the DeviceStore instance. Do not attempt to initialize directly.
Note:
Device state updates are delivered through the state publisher. Subscribe to it to receive real-time updates about microphone, camera, network and other states.

Features

Microphone Management: Open/close microphone, set capture volume and output volume.
Camera Management: Open/close camera, switch front/rear camera, set mirror and video quality.
Audio Route: Switch between speaker and earpiece.
Network Status: Real-time monitoring of network quality information.

Subscribable Data

DeviceState fields are described below:
Property
Type
Description
microphoneStatus
Microphone status.
microphoneLastError
Microphone error, used to extract error information when an error occurs.
captureVolume
Int
Capture volume, with a value range from 0 to 100.
currentMicVolume
Int
Current user's actual output volume.
outputVolume
Int
Maximum output volume, with a value range from 0 to 100.
cameraStatus
Camera status.
cameraLastError
Camera error, used to extract error information when an error occurs.
isFrontCamera
Bool
Whether it's front camera.
localMirrorType
Mirror state.
localVideoQuality
Local video quality.
currentAudioRoute
Current audio route location.
screenStatus
Screen sharing status.
networkInfo
Network information.
networkType
Current network type.
microphoneList
Current microphone device list. Only populated on desktop platforms, it is empty on mobile platforms.
currentMicrophone
Current microphone device, an empty deviceId means no microphone is selected.
microphoneVolume
Int
Microphone capture volume, with a value range from 0 to 100.
microphoneInputLevel
Int
Real-time level value used to display the microphone volume bar, range 0-100.
Only updated while the microphone test is running, see startMicrophoneTest.
cameraList
Camera device list. On desktop platforms it contains all the cameras, on mobile platforms it contains the logical front camera and rear camera.
currentCamera
Current camera device, an empty deviceId means no camera is selected.
speakerList
Speaker device list. On desktop platforms it contains all the speakers, on mobile platforms it contains the logical speaker and earpiece.
currentSpeaker
Current speaker device, an empty deviceId means no speaker is selected.
speakerVolume
Int
Speaker playback volume, with a value range from 0 to 100.
speakerOutputLevel
Int
Speaker real-time output level value, range 0-100.
Only updated while the speaker test is running, see startSpeakerTest.

API List

Function
Description
shared
Singleton object.
Open local microphone.
Close local microphone.
Set microphone capture volume.
Set speaker playback volume.
Select microphone device.
Start microphone test.
Stop microphone test.
Select speaker device.
Start speaker test.
Stop speaker test.
Start camera test.
Stop camera test.
Open local camera.
Close local camera.
Select camera device.
Switch mirror state.
Update video quality.
Set capture volume, use setMicrophoneVolume instead.
Set output volume, use setSpeakerVolume instead.
Set audio route, use setCurrentSpeaker instead.
Switch camera, use setCurrentCamera instead.
reset
Reset to default state.

Getting Instance

shared

Singleton object.

Microphone Operations

openLocalMicrophone

Open local microphone.
public func openLocalMicrophone(completion: CompletionClosure?) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
completion
Whether operation succeeded.

closeLocalMicrophone

Close local microphone.
public func closeLocalMicrophone() {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.

setMicrophoneVolume

Set microphone capture volume.
public func setMicrophoneVolume(_ volume: Int) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
volume
Int
Capture volume, with a value range from 0 to 100.

setSpeakerVolume

Set speaker playback volume.
public func setSpeakerVolume(_ volume: Int) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
volume
Int
Playback volume, with a value range from 0 to 100.

setCurrentMicrophone

Set current microphone device
Only supported on desktop platforms, mobile platforms do not allow switching the microphone device and calling it has no effect there. It takes effect only when the microphone is on.
public func setCurrentMicrophone(_ microphone: DeviceInfo) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
microphone
Microphone device, an element of microphoneList.

startMicrophoneTest

Start microphone test, the capture level is reported to microphoneInputLevel in real time, with a capture interval in milliseconds.
public func startMicrophoneTest(interval: Int) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
interval
Int
Capture interval in milliseconds. Default is 200ms.

stopMicrophoneTest

Stop microphone test.
public func stopMicrophoneTest() {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.

Speaker Operations

setCurrentSpeaker

Set current speaker device.
public func setCurrentSpeaker(_ speaker: DeviceInfo) {
    fatalError("\\(#function) must be overridden by subclass")
}
Supported on all platforms: on desktop platforms any device in speakerList can be selected, on mobile platforms only the logical speaker/earpiece switch takes effect.
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
speaker
Speaker device, an element of speakerList.

startSpeakerTest

Start speaker test, the playback level is reported to speakerOutputLevel in real time
An audio file is played during the test, the speaker device in use can be verified.
public func startSpeakerTest(filePath: String) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
filePath
String
Audio file path used for the test playback. Required; an empty value returns an invalid-parameter error.

stopSpeakerTest

Stop speaker test.
public func stopSpeakerTest() {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.

Camera Operations

startCameraTest

Start camera test, if camera opens successfully, the view will be rendered to the set CameraView.
public func startCameraTest(
    cameraView: UIView,
    completion: CompletionClosure?
) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
cameraView
UIView
Render view id for camera capture, obtained from CameraView.onViewCreated. Pass 0 to set no render target.
completion
Whether operation succeeded.

stopCameraTest

Stop camera test.
public func stopCameraTest() {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.

openLocalCamera

Open local camera.
public func openLocalCamera(
    isFront: Bool,
    completion: CompletionClosure?
) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
isFront
Bool
Whether front camera.
completion
Whether operation succeeded.

closeLocalCamera

Close local camera.
public func closeLocalCamera() {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.

setCurrentCamera

Set current camera device
Supported on all platforms: on desktop platforms any device in cameraList can be selected, on mobile platforms it is equivalent to switching between the front and rear cameras. It takes effect only when the camera is on.
public func setCurrentCamera(_ camera: DeviceInfo) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
camera
Camera device, an element of cameraList.

switchMirror

Switch mirror state.
public func switchMirror(mirrorType: MirrorType) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
mirrorType
Mirror state.

updateVideoQuality

Update video quality.
public func updateVideoQuality(_ quality: VideoQuality, orientation: VideoOrientation = .portrait) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
quality
Video quality.
orientation
Video orientation. Defaults to portrait. Pass landscape to use the base (width x height) resolution.

Deprecated

setCaptureVolume

Set capture volume (deprecated, use setMicrophoneVolume instead).
Warning:
Deprecated: Use setMicrophoneVolume instead. Will be removed in version 5.5.
@available(*, deprecated, message: "Use setMicrophoneVolume instead. Will be removed in version 5.5.")
public func setCaptureVolume(volume: Int) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
volume
Int
Capture volume, with a value range from 0 to 100.

setOutputVolume

Set maximum output volume (deprecated, use setSpeakerVolume instead).
Warning:
Deprecated: Use setSpeakerVolume instead. Will be removed in version 5.5.
@available(*, deprecated, message: "Use setSpeakerVolume instead. Will be removed in version 5.5.")
public func setOutputVolume(_ volume: Int) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
volume
Int
Maximum volume, with a value range from 0 to 100.

setAudioRoute

Set audio route (deprecated, use setCurrentSpeaker instead).
Warning:
Deprecated: Use setCurrentSpeaker instead. Will be removed in version 5.5.
@available(*, deprecated, message: "Use setCurrentSpeaker instead. Will be removed in version 5.5.")
public func setAudioRoute(_ route: AudioRoute) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
route
Route location.

switchCamera

Switch camera (deprecated, use setCurrentCamera instead).
Warning:
Deprecated: Use setCurrentCamera instead. Will be removed in version 5.5.
@available(*, deprecated, message: "Use setCurrentCamera instead. Will be removed in version 5.5.")
public func switchCamera(isFront: Bool) {
    fatalError("\\(#function) must be overridden by subclass")
}
Version
Supported since version 3.5.
Parameters
Parameter
Type
Description
isFront
Bool
Whether front camera.

Reset

reset

Reset to default state.
public func reset() { 
    fatalError("\\(#function) must be overridden by subclass") 
}
Version
Supported since version 3.5.

Data Structures

DeviceType

Device type.
Enum Value
Value
Description
microphone
1
Microphone type.
camera
2
Camera type.
screenShare
3
Screen sharing type.

DeviceError

Device related error codes.
Enum Value
Value
Description
noError
0
Operation successful.
noDeviceDetected
1
No device detected.
noSystemPermission
2
No system permission.
notSupportCapture
3
Capture not supported.
occupiedError
4
Device occupied.
unknownError
5
Unknown error.

DeviceStatus

Device on/off status.
Enum Value
Value
Description
off
0
Off.
on
1
On.

AudioRoute

Audio route.
Enum Value
Value
Description
speakerphone
0
Speaker, using speaker to play (i.e., "hands-free"), located at the bottom of the phone, louder sound, suitable for playing music out loud.
earpiece
1
Earpiece, using earpiece to play, located at the top of the phone, quieter sound, suitable for private call scenarios.

VideoQuality

Video quality level. The final encoding resolution is determined by the combination of this level and VideoOrientation: landscape keeps the base resolution (width x height), portrait swaps the width and height.
Enum Value
Value
Description
quality360P
1
360P. Landscape resolution is 640 x 360; portrait (width and height swapped) is 360 x 640.
quality540P
2
540P. Landscape resolution is 960 x 540; portrait (width and height swapped) is 540 x 960.
quality720P
3
720P. Landscape resolution is 1280 x 720; portrait (width and height swapped) is 720 x 1280.
quality1080P
4
1080P. Landscape resolution is 1920 x 1080; portrait (width and height swapped) is 1080 x 1920.

VideoOrientation

Video orientation. Combined with VideoQuality to determine the final encoding resolution: landscape keeps the base resolution (width x height), portrait swaps the width and height.
Enum Value
Value
Description
landscape
0
Landscape, the encoding resolution width is greater than the height (e.g. 1280 x 720).
portrait
1
Portrait, the encoding resolution height is greater than the width (e.g. 720 x 1280).

NetworkQuality

Network quality.
Enum Value
Value
Description
unknown
0
Unknown network.
excellent
1
Excellent.
good
2
Good.
poor
3
Poor.
bad
4
Bad.
veryBad
5
Very bad.
down
6
Disconnected.

MirrorType

Camera mirror state.
Enum Value
Value
Description
auto
0
Auto, front camera mirrored, rear camera not mirrored.
enable
1
Both front and rear cameras mirrored.
disable
2
Neither front nor rear camera mirrored.

NetworkType

Network type.
Enum Value
Value
Description
unknown
0
Unknown or unidentified network type.
wifi
1
WiFi network connection.
cellular
2
Cellular/mobile data network connection.

DeviceInfo

Device information.
Property
Type
Description
deviceId
String
Device ID.
deviceName
String
Device name.

NetworkInfo

Network information.
Property
Type
Description
userID
String
User unique ID.
quality
Network quality.
upLoss
UInt32
Uplink packet loss rate, with a value range from 0 to 100.
downLoss
UInt32
Downlink packet loss rate, with a value range from 0 to 100.
delay
UInt32
Latency (unit: milliseconds).

DeviceState

Device state.
Property
Type
Description
microphoneStatus
Microphone status.
microphoneLastError
Microphone error, used to extract error information when an error occurs.
captureVolume
Int
Capture volume, with a value range from 0 to 100.
currentMicVolume
Int
Current user's actual output volume.
outputVolume
Int
Maximum output volume, with a value range from 0 to 100.
cameraStatus
Camera status.
cameraLastError
Camera error, used to extract error information when an error occurs.
isFrontCamera
Bool
Whether it's front camera.
localMirrorType
Mirror state.
localVideoQuality
Local video quality.
currentAudioRoute
Current audio route location.
screenStatus
Screen sharing status.
networkInfo
Network information.
networkType
Current network type.
microphoneList
Current microphone device list. Only populated on desktop platforms, it is empty on mobile platforms.
currentMicrophone
Current microphone device, an empty deviceId means no microphone is selected.
microphoneVolume
Int
Microphone capture volume, with a value range from 0 to 100.
microphoneInputLevel
Int
Real-time level value used to display the microphone volume bar, range 0-100.
Only updated while the microphone test is running, see startMicrophoneTest.
cameraList
Camera device list. On desktop platforms it contains all the cameras, on mobile platforms it contains the logical front camera and rear camera.
currentCamera
Current camera device, an empty deviceId means no camera is selected.
speakerList
Speaker device list. On desktop platforms it contains all the speakers, on mobile platforms it contains the logical speaker and earpiece.
currentSpeaker
Current speaker device, an empty deviceId means no speaker is selected.
speakerVolume
Int
Speaker playback volume, with a value range from 0 to 100.
speakerOutputLevel
Int
Speaker real-time output level value, range 0-100.
Only updated while the speaker test is running, see startSpeakerTest.

Usage Example

// Get singleton instance
let store = DeviceStore.shared
// Subscribe to state changes
store.state.subscribe { state in
    print("Microphone status: \\(state.microphoneStatus)")
    print("Camera status: \\(state.cameraStatus)")
    print("Network quality: \\(state.networkInfo.quality)")
}
// Open microphone
store.openLocalMicrophone { code, message in
    if code == 0 {
        print("Microphone opened successfully")
    }
}
// Open front camera
store.openLocalCamera(isFront: true) { code, message in
    if code == 0 {
        print("Camera opened successfully")
    }
}

Anterior: CoHostStorePróximo: GiftStore

Ajuda e Suporte

Esta página foi útil?

comentários

Search
    Enter keywords to search documentation