Merge pull request #91 from zoom/dev

docs: update troubleshooting and changelog for v1.0.2

Author: MaxMansfield

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

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:

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

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

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