diff --git a/CHANGELOG.md b/CHANGELOG.md index 8678073..9eb08d1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,28 @@ All notable changes to the Zoom RTMS SDK will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [1.0.2] - 2026-01-30 + +### Added + +- **Video SDK support**: Added `session_id` parameter to `join()` for Video SDK events (`session.rtms_started`) alongside existing Meeting SDK support (`meeting.rtms_started`) ([#80](https://github.com/zoom/rtms/issues/80)) +- **Python `rtms.run()`**: New simplified threading model that handles event loop management, client polling, and graceful shutdown automatically ([#88](https://github.com/zoom/rtms/issues/88)) + +### Fixed + +- **Default media params**: Apply sensible defaults (e.g., `AUDIO_MULTI_STREAMS`) when callbacks are registered without explicit media configuration +- **Media param reconfiguration**: Calling `setAudioParams()`/`setVideoParams()` after registering a callback now triggers reconfiguration +- **Codec validation**: Added validation at C++ layer - JPG/PNG codecs require fps ≤ 5, H264 allows fps up to 30 +- **Python docs deployment**: Fixed documentation deployment path (renamed `docs/rtms` to `docs/py`) + +### Security + +- Upgraded cmake-js to v8 to resolve tar dependency vulnerabilities (GHSA-8qq5-rm4j-mr97, GHSA-r6q2-hw4h-h46w, GHSA-34x7-hfp2-rc4v) + +### Changed + +- Updated Python installation instructions to use production PyPI instead of TestPyPI + ## [1.0.0] - 2026-01-22 ### Added diff --git a/README.md b/README.md index 07c07a5..ee0e62f 100644 --- a/README.md +++ b/README.md @@ -545,63 +545,13 @@ task doctor # Check Node, Python, CMake, Docker versions # Setup project task setup # Fetch SDK and install dependencies -# Building modules -task build:js # Build Node.js for current platform -task build:js:linux # Build Node.js for Linux (via Docker) -task build:js:darwin # Build Node.js for macOS - -task build:py # Build Python for current platform -task build:py:linux # Build Python wheel for Linux (via Docker) -task build:py:darwin # Build Python wheel for macOS - -task build:local # Build all bindings for local platform -task build:linux # Build all bindings for Linux (via Docker) -task build:all # Build everything for all platforms - -# Creating prebuilds for distribution -task prebuild:js # Create Node.js prebuilds for all platforms -task prebuild:js:linux # Create Node.js prebuild for Linux only -task prebuild:js:darwin # Create Node.js prebuild for macOS only - -# Testing -task test:js # Run Node.js tests (local) -task test:js:linux # Run Node.js tests in Linux Docker -task test:py # Run Python tests (local) -task test:py:linux # Run Python tests in Linux Docker -task test:local # Run all tests locally -task test:linux # Run all tests in Linux Docker -task test:all # Run tests on all platforms - -# Manual/Interactive testing -task manual:js # Run interactive Node.js test -task manual:py # Run interactive Python test - -# Publishing to registries -task publish:js # Upload Node.js prebuilds to GitHub releases -task publish:py # Upload Python wheels to production PyPI -task publish:py:test # Upload Python wheels to TestPyPI - -# Documentation -task docs:js # Generate Node.js API documentation -task docs:py # Generate Python API documentation -task docs:all # Generate all documentation - -# Utility commands -task clean # Remove all build artifacts -task clean:build # Remove only build outputs (keep dependencies) - # Build modes BUILD_TYPE=Debug task build:js # Build in debug mode BUILD_TYPE=Release task build:js # Build in release mode (default) -``` -**Task Features:** -- **Smart caching**: Skips unchanged builds (checksum-based) -- **Parallel execution**: Runs independent tasks concurrently -- **Environment checks**: Validates versions before building -- **Cross-platform**: Works on macOS, Linux, Windows - -These commands help you manage different aspects of the build process and testing workflow. The unified structure makes it easy to build, package, and publish for multiple languages and platforms. +# Debug logging for C SDK callbacks +RTMS_DEBUG=ON task build:js # Enable verbose callback logging +``` ## Troubleshooting @@ -656,6 +606,28 @@ Try both debug and release modes (`npm run debug` or `npm run release`) ### 5. Dependencies Verify all prerequisites are installed +### 6. Audio Defaults Mismatch +This SDK uses different default audio parameters than the raw RTMS WebSocket protocol for better out-of-the-box quality. If you need to match the WebSocket protocol defaults, see [#92](https://github.com/zoom/rtms/issues/92) for details. + +### 7. Identifying Speakers with Mixed Audio Streams +When using `AUDIO_MIXED_STREAM`, the audio callback's metadata does not identify the current speaker since all participants are mixed into a single stream. To identify who is speaking, use the `onActiveSpeakerEvent` callback: + +**Node.js:** +```javascript +client.onActiveSpeakerEvent((timestamp, userId, userName) => { + console.log(`Active speaker: ${userName} (${userId})`); +}); +``` + +**Python:** +```python +@client.onActiveSpeakerEvent +def on_active_speaker(timestamp, user_id, user_name): + print(f"Active speaker: {user_name} ({user_id})") +``` + +This callback notifies your application whenever the active speaker changes in the meeting. You can also use the lower-level `onEventEx` function with the active speaker event type directly. See [#80](https://github.com/zoom/rtms/issues/80) for more details. + ## For Maintainers If you're a maintainer looking to build, test, or publish new releases of the RTMS SDK, please refer to [PUBLISHING.md](PUBLISHING.md) for comprehensive documentation on: diff --git a/examples/meetings.md b/examples/meetings.md index 9892090..b1cd24e 100644 --- a/examples/meetings.md +++ b/examples/meetings.md @@ -218,6 +218,74 @@ def handle_webhook(payload, request, response): response.send({'status': 'ok'}) ``` +## Audio Configuration + +### SDK Defaults vs WebSocket Defaults + +> **Note:** This SDK uses different default audio parameters than the raw RTMS WebSocket protocol. This provides better quality out-of-the-box but may require adjustment if you need to match the WebSocket defaults. This will be aligned in v2.0 ([#92](https://github.com/zoom/rtms/issues/92)). + +| Parameter | SDK Default | WebSocket Default | +|-----------|-------------|-------------------| +| Codec | OPUS (4) | L16 (1) | +| Sample Rate | 48kHz (3) | 16kHz (1) | +| Channel | Stereo (2) | Mono (1) | +| Data Option | AUDIO_MULTI_STREAMS (2) | AUDIO_MIXED_STREAM (1) | +| Duration | 20ms | 20ms | +| Frame Size | 960 | 320 | + +### Using SDK Defaults (Recommended for v1.x) + +The SDK defaults provide high-quality audio with per-speaker attribution: + +```javascript +// No configuration needed - SDK defaults are applied automatically +client.onAudioData((data, timestamp, metadata) => { + // metadata.userId and metadata.userName are populated + console.log(`Audio from ${metadata.userName}`); +}); +``` + +### Matching WebSocket Defaults + +If you need to match the raw WebSocket protocol defaults: + +```javascript +client.setAudioParams({ + contentType: rtms.AudioContentType.RAW_AUDIO, + codec: rtms.AudioCodec.L16, + sampleRate: rtms.AudioSampleRate.SR_16K, + channel: rtms.AudioChannel.MONO, + dataOpt: rtms.AudioDataOption.AUDIO_MIXED_STREAM, + duration: 20, + frameSize: 320 // 16000 * 0.02 * 1 +}); + +client.onAudioData((data, timestamp, metadata) => { + // Note: AUDIO_MIXED_STREAM does not provide per-speaker metadata + console.log(`Mixed audio: ${data.length} bytes`); +}); +``` + +### Python Configuration + +```python +# Using SDK defaults (recommended for v1.x) +@client.onAudioData +def on_audio(data, size, timestamp, metadata): + print(f'Audio from {metadata.userName}') + +# Matching WebSocket defaults +client.set_audio_params( + content_type=rtms.AudioContentType.RAW_AUDIO, + codec=rtms.AudioCodec.L16, + sample_rate=rtms.AudioSampleRate.SR_16K, + channel=rtms.AudioChannel.MONO, + data_opt=rtms.AudioDataOption.AUDIO_MIXED_STREAM, + duration=20, + frame_size=320 +) +``` + ## Processing Media Streams ### Node.js - Audio Processing diff --git a/examples/videosdk.md b/examples/videosdk.md index aa725a1..926f3c4 100644 --- a/examples/videosdk.md +++ b/examples/videosdk.md @@ -6,6 +6,8 @@ Real-time media streaming from custom Zoom Video SDK applications. The RTMS SDK provides the same API for accessing real-time media streams from applications built with Zoom Video SDK. This enables you to build custom video experiences and still access the underlying media streams for processing, recording, or integration. +> **Audio Configuration:** This SDK uses different default audio parameters than the raw RTMS WebSocket protocol. See [Audio Configuration](meetings.md#audio-configuration) in the Meetings documentation for details on SDK defaults vs WebSocket defaults. + ## Quick Start ### Node.js diff --git a/examples/webinars.md b/examples/webinars.md index 2802c8f..4a88712 100644 --- a/examples/webinars.md +++ b/examples/webinars.md @@ -6,6 +6,8 @@ Real-time media streaming from Zoom Webinars. The RTMS SDK provides the same API for accessing real-time media streams from Zoom Webinars. The key difference is in how you obtain the webhook payload and join parameters from Zoom's Webinar RTMS webhooks. +> **Audio Configuration:** This SDK uses different default audio parameters than the raw RTMS WebSocket protocol. See [Audio Configuration](meetings.md#audio-configuration) in the Meetings documentation for details on SDK defaults vs WebSocket defaults. + ## Quick Start ### Node.js