Mini-program SDK Guide
WeChat mini-program live-pusher/live-player public interface and limits.
The WeChat mini-program SDK is written in TypeScript and aligns with the Agora mini-program API: 4 interfaces, 32 methods, 45 overloads, 14 events, 4 enums and 43 error codes. Media capture and streaming are provided by the mini-program's native components through an injected port; the SDK does not bundle a media stack.
Prerequisites
- WeChat DevTools plus a mini-program base library (
live-pusher/live-playercomponents available). The SDK itself is plain TypeScript with no native dependencies. - An App ID and a token service (see Enable Services and Get Credentials).
- Platform capabilities are injected:
MiniProgramSessionService(channels/token),MiniProgramMediaPort(the push/pull component bridge),
an optional MiniProgramEventSource (component/long-connection events) and a log-upload endpoint. The SDK ships no media stack and does not pretend it can capture.
Installation
pnpm --filter @nimeet/rtc-miniprogram build # source in sdk/mini-program, output in sdk/mini-program/buildThe mini-program project adds sdk/mini-program/build as a local dependency (miniprogram_npm, or copied straight into utils/). No npm package is published yet: @nimeet/rtc-miniprogram is only available inside the codebase.
Get a token
Your backend issues the token with POST /v1/tokens; the client only receives { appId, rtcToken, rtcUid }. The first argument of Client.join(channelKey, channel, uid, isAudioOnly, …) on the mini program is the token string, as on every other platform; for the interface definition-level semantics see AccessToken2 Semantics and Privileges.
Join a channel
import { Client } from '@nimeet/rtc-miniprogram';
// the platform bridge is injected by the host: the WeChat component, your backend, and an optional log-upload endpoint.
const client = new Client({ runtime: { session, media, events } });
await client.init(appId);
await client.join(token, 'channel-a', 1234, /* isAudioOnly */ false);
const pushUrl = await client.publish(); // live-pusher push URL
await client.setRole('audience'); // switching to audience invalidates the push URL (documented semantics)
await client.leave();init(appId, onSuccess?, onFailure?): an empty App ID → throws-101(invalid App ID).join(...): notinited →-7; empty channel name →-102; invalid uid →-121; joining twice →-17.- Channel/token requests all go through the injected
session; the SDK never connects to the network itself.
Publishing and subscribing
await client.publish(); // Promise<string>: the push URL; also sets the role to host
await client.subscribe(5678, { video: true }); // Promise<{ url, rotation }>: the pull URL and the rotation angle
await client.unsubscribe(5678);
await client.muteLocal('all'); // 'audio' | 'video' | 'all'
await client.mute(5678, 'audio');setRemoteVideoStreamType(uid, 0 | 1) selects the high or low stream; setAudioCodec(AudioCodec.PCMU | PCMA | G722) sets the IoT codec. Calling any of the methods above without being in a channel returns -3 (the SDK is not ready).
Events
on(event, callback?) / off(event): the 14 events match the reference version name by name, and an unknown event name throws -2.
| Event | Source | Payload |
|---|---|---|
stream-added / stream-removed | Component/long-connection event source | { uid } |
update-url | Same as above | { uid, url } |
video-rotation | Same as above | { uid, rotation } |
mute-audio / mute-video / unmute-audio / unmute-video | Same as above | { uid } |
client-banned | Kicked by the server | The event payload; the client state also drops back to initialized (and the push URL is invalidated) |
token-privilege-will-expire / token-privilege-did-expire | Token state | No payload (call renewToken as documented) |
channel-media-relay-event / channel-media-relay-state | Cross-channel relay (explicitly unsupported on this platform, see below) | { code } / { code, state } |
error | Any asynchronous failure | { code, reason } |
on returns a listener set that off(event) clears as a whole; one listener throwing does not affect the others.
Error handling
The error object is MiniProgramError, and code is negative (positive codes are negated, matching Agora's documentation numbers):
| code | Meaning | Trigger |
|---|---|---|
-1 | General error | Platform/backend failure (onFailure receives it too) |
-2 | Invalid argument | The target is not audio/video/all, the event name is unknown, bitrate/position and the like |
-3 | Not ready yet | publish/subscribe/mute before joining a channel |
-4 | Unsupported in this state/build | The three cross-channel relay methods and Log.uploadLogs (not supported in the current version) |
-5 | Request refused | A refusal under the documented semantics |
-7 | Not initialized | join and so on before init |
-8 | Invalid state | Any method after destroy() |
-17 / -18 | Join refused / leave refused | Joining twice / leaving without having joined |
-101 / -102 / -121 | Invalid App ID / channel name / uid | Argument validation |
-109 / -110 / -123 | Token expired / token invalid / banned by the server | Returned by the platform |
The following members are not supported in the current version and return error code -4: Client.startChannelMediaRelay, Client.updateChannelMediaRelay, Client.stopChannelMediaRelay (they need the SD-RTN relay service, which is enabled by a support ticket), Log.uploadLogs (this platform has no log-upload endpoint). All four method names are real members; calling them throws -4 and never silently succeeds.
Troubleshooting
| Symptom | Cause | Handling |
|---|---|---|
-7 | init was not called first | Call await client.init(appId) first |
The URL returned by publish() will not open | The host injected no working live-pusher bridge | Check the MiniProgramMediaPort.publish implementation |
-4 on cross-channel relay | The capability needs the SD-RTN relay service | Ask the server side to enable it if you need relay; the client keeps refusing explicitly |
| No callback for an event | MiniProgramEventSource was not injected, or the event name is not one of the 14 documented events | Inject the event source; unknown event names throw -2 |
| Enums have no explicit values | StreamType / UidType list keys only | The implementation assigns values in declaration order; do not rely on numeric values |
| Why types are compared by name only | The reference version writes callbacks as function and options as object | See the note at the top of this page; compare.types = name-only |
Next steps
- Full interfaces and overloads: API reference for this platform
- Error codes and troubleshooting: Error code table, FAQ
- Issue tokens on your server: Token authentication
Platform information
| Item | value |
|---|---|
| Platform | Mini program(WeChat) |
| Language | TypeScript |
| SDK package | @nimeet/rtc-miniprogram |
| Interface version | 2.6.5 |
| Compatible Agora API | Agora mini-program API |
The public interfaces are aligned with the Agora mini-program API; installation and runtime requirements are listed under Prerequisites above.
Availability
This platform's SDK: Generally available. The examples use the public API; runtime capability follows the published SDK package.
join-channel flow
The method names, parameter types and return values match the API reference for the same platform. Where a method has several overloads, the most common one is shown here; see the API reference for all overloads.
| Step | Interface | Method | Overload count |
|---|---|---|---|
| Join a channel | Client | join | 1 |
| Leave a channel | Client | leave | 1 |
| publish the local track | Client | publish | 1 |
| Renew the Token | Client | renewToken | 1 |
| subscribe to remote media | Client | subscribe | 1 |
join(channelKey: string, channel: string, uid: number|string, isAudioOnly: boolean, UidType?: UidType, onSuccess?: function, onFailure?: function): Promise<void>
leave(onSuccess?: function, onFailure?: function): Promise<void>
publish(onSuccess?: function, onFailure?: function): Promise<string>
renewToken(token: string, onSuccess?: function, onFailure?: function): Promise<void>
subscribe(uid: number, options?: object, onSuccess?: function, onFailure?: function): Promise<object>Events and callbacks
| Interface | event name | listener parameters |
|---|---|---|
Client | channel-media-relay-event | Function |
Client | channel-media-relay-state | Function |
Client | client-banned | Function |
Client | error | Function |
Client | mute-audio | Function |
Client | mute-video | Function |
Client | stream-added | Function |
Client | stream-removed | Function |
Client | token-privilege-did-expire | Function |
Client | token-privilege-will-expire | Function |
Client | unmute-audio | Function |
Client | unmute-video | Function |
Client | update-url | Function |
Client | video-rotation | Function |
Error codes
This SDK does not expose error-code constants. For platform errors see Error codes; for cross-platform SDK error identifiers see SDK error identifiers.