refactor(frontend): replace emitData() with 'raw' structure type

Per PR review feedback, drop the parallel emitData() methods at every
layer in favour of extending sendMessageToStreamer's structure
vocabulary with 'raw'. Single entry point for to-streamer messages,
binary payloads ride the same path as every other typed structure.
Wire format unchanged; existing callers do not need to update.

Author: mcottontensor

.changeset/data-channel-raw-bytes.md

@@ -2,4 +2,11 @@
 "@epicgames-ps/lib-pixelstreamingfrontend-ue5.7": minor
 ---
 
-Add `PixelStreaming.emitData(messageType, bytes)` for sending raw byte payloads through the data channel without JSON encoding (#608). The bytes are sent as the payload of a registered to-streamer message type — the registered id is prepended as a single byte, the rest of the buffer is the application's payload verbatim. Useful for custom binary protocols (e.g. UTF-8 strings, packed structs) where the receiving UE side decodes the payload itself. The lower-level `WebRtcPlayerController.emitData` and `SendMessageController.sendBytesToStreamer` are also exposed for advanced callers.
+Add `'raw'` to the structure vocabulary in to-streamer message types (#608). A field declared as `'raw'` accepts a `Uint8Array` and is written into the message buffer verbatim, enabling custom binary protocols (e.g. UTF-8 strings, packed structs) where the receiving UE side decodes the payload itself. Send via the existing `sendMessageToStreamer` path:
+
+```ts
+streamMessageController.toStreamerMessages.set('MyBinaryMsg', { id: 137, structure: ['raw'] });
+sendMessageController.sendMessageToStreamer('MyBinaryMsg', [myUint8Array]);
+```
+
+Existing structure types and call sites are unchanged.

Frontend/library/src/PixelStreaming/PixelStreaming.ts

@@ -813,29 +813,6 @@ export class PixelStreaming {
         return true;
     }
 
-    /**
-     * Send raw bytes to the UE application through the data channel without
-     * any JSON encoding or per-field encoding. The bytes are sent as the
-     * payload of a registered to-streamer message type — the message id
-     * is prepended as a single byte.
-     *
-     * The message type must be registered via
-     * `streamMessageController.toStreamerMessages.set(...)` so the id is
-     * known. Useful for custom binary protocols where the receiving side
-     * (UE) decodes the payload itself.
-     *
-     * @param messageType - Name of a registered to-streamer message type.
-     * @param bytes - Payload to send, not including the message id byte.
-     * @returns true if the bytes were submitted, false if rejected (video
-     *   not ready, message type not registered, or data channel not open).
-     */
-    public emitData(messageType: string, bytes: Uint8Array | ArrayBuffer): boolean {
-        if (!this._webRtcController.videoPlayer.isVideoReady()) {
-            return false;
-        }
-        return this._webRtcController.emitData(messageType, bytes);
-    }
-
     /**
      * Send a console command to UE application. Only allowed if UE has signaled that it allows
      * console commands.

Frontend/library/src/UeInstanceMessage/SendMessageController.test.ts

@@ -0,0 +1,79 @@
+import { DataChannelSender } from '../DataChannel/DataChannelSender';
+import { SendMessageController } from './SendMessageController';
+import { StreamMessageController } from './StreamMessageController';
+
+describe('SendMessageController', () => {
+    let streamMessageController: StreamMessageController;
+    let dataChannelSender: DataChannelSender;
+    let sendData: jest.Mock;
+    let controller: SendMessageController;
+
+    beforeEach(() => {
+        streamMessageController = new StreamMessageController();
+        sendData = jest.fn();
+        dataChannelSender = {
+            canSend: () => true,
+            sendData
+        } as unknown as DataChannelSender;
+        controller = new SendMessageController(dataChannelSender, streamMessageController);
+    });
+
+    describe("structure: ['raw']", () => {
+        it('prepends the message id byte and copies the Uint8Array verbatim', () => {
+            streamMessageController.toStreamerMessages.set('MyBinaryMsg', {
+                id: 137,
+                structure: ['raw']
+            });
+
+            const payload = new Uint8Array([0x00, 0x01, 0xff, 0x42]);
+            controller.sendMessageToStreamer('MyBinaryMsg', [payload]);
+
+            expect(sendData).toHaveBeenCalledTimes(1);
+            const sent = new Uint8Array(sendData.mock.calls[0][0] as ArrayBuffer);
+            expect(Array.from(sent)).toEqual([137, 0x00, 0x01, 0xff, 0x42]);
+        });
+
+        it('handles an empty payload', () => {
+            streamMessageController.toStreamerMessages.set('EmptyMsg', {
+                id: 200,
+                structure: ['raw']
+            });
+
+            controller.sendMessageToStreamer('EmptyMsg', [new Uint8Array(0)]);
+
+            const sent = new Uint8Array(sendData.mock.calls[0][0] as ArrayBuffer);
+            expect(Array.from(sent)).toEqual([200]);
+        });
+
+        it('packs raw alongside other typed fields', () => {
+            streamMessageController.toStreamerMessages.set('Mixed', {
+                id: 50,
+                structure: ['uint8', 'raw', 'uint8']
+            });
+
+            controller.sendMessageToStreamer('Mixed', [
+                0xaa,
+                new Uint8Array([0xbb, 0xcc]),
+                0xdd
+            ]);
+
+            const sent = new Uint8Array(sendData.mock.calls[0][0] as ArrayBuffer);
+            expect(Array.from(sent)).toEqual([50, 0xaa, 0xbb, 0xcc, 0xdd]);
+        });
+    });
+
+    describe('backwards compatibility', () => {
+        it('still packs typed structures as before', () => {
+            streamMessageController.toStreamerMessages.set('Typed', {
+                id: 1,
+                structure: ['uint8', 'uint16']
+            });
+
+            controller.sendMessageToStreamer('Typed', [0x10, 0x2030]);
+
+            const sent = new Uint8Array(sendData.mock.calls[0][0] as ArrayBuffer);
+            // id (1), uint8 0x10, uint16 0x2030 little-endian = 0x30, 0x20
+            expect(Array.from(sent)).toEqual([1, 0x10, 0x30, 0x20]);
+        });
+    });
+});

Frontend/library/src/UeInstanceMessage/SendMessageController.ts

@@ -26,7 +26,7 @@ export class SendMessageController {
      * @param messageData - the message data we are sending over the data channel
      * @returns - nil
      */
-    sendMessageToStreamer(messageType: string, messageData?: Array<number | string>) {
+    sendMessageToStreamer(messageType: string, messageData?: Array<number | string | Uint8Array>) {
         if (messageData === undefined) {
             messageData = [];
         }
@@ -54,16 +54,22 @@ export class SendMessageController {
                                 return 'number';
                             case 'string':
                                 return 'string';
+                            case 'raw':
+                                return 'Uint8Array';
                         }
                     })
-                    .toString()} ] but received [ ${messageData.map((element: number | string) => typeof element).toString()} ]`
+                    .toString()} ] but received [ ${messageData
+                    .map((element: number | string | Uint8Array) =>
+                        element instanceof Uint8Array ? 'Uint8Array' : typeof element
+                    )
+                    .toString()} ]`
             );
             return;
         }
 
         let byteLength = 0;
         // One loop to calculate the length in bytes of all of the provided data
-        messageData.forEach((element: number | string, idx: number) => {
+        messageData.forEach((element: number | string | Uint8Array, idx: number) => {
             const type = messageFormat.structure[idx];
             switch (type) {
                 case 'uint8':
@@ -92,14 +98,18 @@ export class SendMessageController {
                     // 2 bytes per character
                     byteLength += 2 * (element as string).length;
                     break;
+
+                case 'raw':
+                    byteLength += (element as Uint8Array).byteLength;
+                    break;
             }
         });
 
         const data = new DataView(new ArrayBuffer(byteLength + 1));
         data.setUint8(0, messageFormat.id);
         let byteOffset = 1;
 
-        messageData.forEach((element: number | string, idx: number) => {
+        messageData.forEach((element: number | string | Uint8Array, idx: number) => {
             const type = messageFormat.structure[idx];
             switch (type) {
                 case 'uint8':
@@ -135,6 +145,13 @@ export class SendMessageController {
                         byteOffset += 2;
                     }
                     break;
+
+                case 'raw': {
+                    const bytes = element as Uint8Array;
+                    new Uint8Array(data.buffer).set(bytes, byteOffset);
+                    byteOffset += bytes.byteLength;
+                    break;
+                }
             }
         });
 
@@ -149,44 +166,4 @@ export class SendMessageController {
 
         this.dataChannelSender.sendData(data.buffer);
     }
-
-    /**
-     * Send a raw byte payload for a registered to-streamer message type. The
-     * registered message id is prepended as a single byte, then the bytes
-     * are sent through the data channel as-is — no JSON encoding, no
-     * per-field structure validation.
-     *
-     * Useful for custom protocols where the application owns the binary
-     * payload format on both ends. The application must have called
-     * `streamMessageController.toStreamerMessages.set(...)` (or relied on
-     * a default-registered type such as `UIInteraction`) so the message id
-     * is known.
-     *
-     * @param messageType - Name of a registered to-streamer message type.
-     * @param bytes - Payload to send, not including the message id byte.
-     * @returns true if the bytes were submitted to the data channel; false
-     *   if the message type isn't registered or the channel can't send.
-     */
-    sendBytesToStreamer(messageType: string, bytes: Uint8Array | ArrayBuffer): boolean {
-        const messageFormat = this.toStreamerMessagesMapProvider.toStreamerMessages.get(messageType);
-        if (messageFormat === undefined) {
-            Logger.Error(
-                `Attempted to send raw bytes for message type "${messageType}" but no such type is registered. Register it via streamMessageController.toStreamerMessages.set(...)`
-            );
-            return false;
-        }
-
-        if (!this.dataChannelSender.canSend()) {
-            Logger.Info(`Data channel cannot send yet, skipping raw bytes for: ${messageType}`);
-            return false;
-        }
-
-        const payload = bytes instanceof ArrayBuffer ? new Uint8Array(bytes) : bytes;
-        const buffer = new ArrayBuffer(1 + payload.byteLength);
-        const view = new Uint8Array(buffer);
-        view[0] = messageFormat.id;
-        view.set(payload, 1);
-        this.dataChannelSender.sendData(buffer);
-        return true;
-    }
 }

Frontend/library/src/UeInstanceMessage/StreamMessageController.ts

@@ -8,7 +8,7 @@ export class ToStreamerMessage {
 }
 
 export class StreamMessageController {
-    toStreamerHandlers: Map<string, (messageData?: Array<number | string>) => void>;
+    toStreamerHandlers: Map<string, (messageData?: Array<number | string | Uint8Array>) => void>;
     fromStreamerHandlers: Map<string, (messageType: string, messageData?: ArrayBuffer) => void>;
     //                        Type      Format
     toStreamerMessages: Map<string, ToStreamerMessage>;

Frontend/library/src/WebRtcPlayer/WebRtcPlayerController.ts

@@ -1827,14 +1827,6 @@ export class WebRtcPlayerController {
         this.streamMessageController.toStreamerHandlers.get('Command')([JSON.stringify(descriptor)]);
     }
 
-    /**
-     * Send raw bytes through the data channel for a registered to-streamer
-     * message type. See {@link SendMessageController.sendBytesToStreamer}.
-     */
-    emitData(messageType: string, bytes: Uint8Array | ArrayBuffer): boolean {
-        return this.sendMessageController.sendBytesToStreamer(messageType, bytes);
-    }
-
     /**
      * Send a console command message
      */