@pipedog/serializer-protobuf 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2024–2026, Daily
+Copyright (c) 2026, pipedog contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/NOTICE

@@ -0,0 +1,9 @@
+pipedog is an unofficial TypeScript port of Pipecat (https://github.com/pipecat-ai/pipecat),
+a framework for voice and multimodal conversational AI created by Daily.
+
+It is not affiliated with or endorsed by Daily. Pipecat is distributed under
+the BSD 2-Clause License, Copyright (c) 2024–2026, Daily; that copyright notice
+and license are retained in LICENSE, and every ported source file carries a
+header naming the upstream file it was derived from.
+
+The upstream commit each file was ported from is recorded in porting/manifest.json.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @pipedog/serializer-protobuf
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`ProtobufFrameSerializer` for pipedog, a port of Pipecat's `pipecat.serializers.protobuf`. It
+speaks Pipecat's `frames.proto` over WebSocket: text, audio, transcription, interruption and
+transport messages, the last as a `MessageFrame` holding JSON. It is the default serializer of
+the WebSocket transports, and the format the official Pipecat browser client uses.
+
+```sh
+bun add @pipedog/serializer-protobuf
+```
+
+```ts
+import { ProtobufFrameSerializer } from "@pipedog/serializer-protobuf/protobuf";
+
+const serializer = new ProtobufFrameSerializer();
+const bytes = await serializer.serialize(frame); // Uint8Array, or null for other frame types
+const decoded = await serializer.deserialize(bytes); // InputAudioRawFrame, InputTransportMessageFrame, ...
+```
+
+Pass it as `serializer` to any transport in
+[`@pipedog/transport-websocket`](../transport-websocket).
+
+## Runtimes
+
+| class | Bun | Node | Deno | Cloudflare Workers |
+|---|:-:|:-:|:-:|:-:|
+| `ProtobufFrameSerializer` | ✅ | ✅ | ✅ | ✅ |
+
+The codec is core's `frames/protobufs/frames_pb2`: a hand-written proto3 codec for the same
+schema, with no dependencies. `compat/smoke.ts` replays the golden vectors on all four runtimes.
+
+## Wire compatibility
+
+Its wire format is the protocol, so it is checked byte for byte:
+
+- **Upstream** (`test/golden.test.ts`, vectors recorded from upstream Pipecat by
+  `tools/golden/serializers.py`). Serializing gives identical bytes for every frame type: unicode
+  text, empty and large ids, mono and stereo audio, with and without `pts`, transcriptions, and
+  interruptions. Transport messages with nested, unicode, emoji, control-character, float and
+  big-int data also match, down to the JSON text, which is written as Python's `json.dumps`
+  writes it. Deserializing upstream's bytes, unknown fields included, gives the same frames.
+- **The official browser client**, `@pipecat-ai/websocket-transport` 1.7.2
+  (`test/client_js_compat.test.ts`, with fixtures from `tools/client-compat/`). Our serializer
+  decodes the bytes the client sends: mic audio and RTVI messages. The client decodes ours:
+  audio and RTVI messages. The client's `frames.proto` predates `InterruptionFrame`, so it logs
+  and ignores interruption, text and transcription frames, from upstream's bots too. A real
+  `PipecatClient` was also run headless against `SingleClientWebsocketServerTransport` with
+  `tools/client-compat/e2e.ts`.
+
+Differences from upstream:
+
+- `uint64` ids are JS numbers, exact up to 2^53.
+- Transport messages are parsed with `JSON.parse`, which rejects the `NaN` and `Infinity` that
+  Python's `json` accepts. Such a message is dropped with an error log.
+- A string field with invalid UTF-8 is decoded with replacement characters, where upstream's
+  protobuf raises `DecodeError`.
+- JavaScript has no separate int and float types, so `2.0` arrives as `2`.
+
+## License
+
+BSD 2-Clause, a port of Pipecat (Copyright (c) 2024–2026 Daily).

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/** Protobuf frame serializer. `@pipedog/serializer-protobuf/protobuf` mirrors `pipecat.serializers.protobuf`. */
+export * from "./protobuf.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,5 @@
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+/** Protobuf frame serializer. `@pipedog/serializer-protobuf/protobuf` mirrors `pipecat.serializers.protobuf`. */
+export * from "./protobuf.js";
+//# sourceMappingURL=index.js.map

package/dist/protobuf.d.ts

@@ -0,0 +1,54 @@
+import { type Frame } from "@pipedog/core/frames/frames";
+import * as frame_protos from "@pipedog/core/frames/protobufs/frames_pb2";
+import { FrameSerializer, type FrameSerializerOptions, type SerializedData } from "@pipedog/core/serializers/base_serializer";
+export interface MessageFrameOptions {
+    /** JSON-encoded message data for transport. */
+    data: string;
+}
+/**
+ * Data class for converting transport messages into Protobuf format.
+ *
+ * - `data`: JSON-encoded message data for transport.
+ */
+export declare class MessageFrame {
+    data: string;
+    constructor(options: MessageFrameOptions);
+    toString(): string;
+}
+type AnyCtor = abstract new (...args: any[]) => unknown;
+type ConcreteCtor = new (options: any) => Frame | MessageFrame;
+/**
+ * Serializer for converting Pipecat frames to/from Protocol Buffer format.
+ *
+ * Provides efficient binary serialization for frame transport over network
+ * connections. Supports text, audio, transcription, and message frames with
+ * automatic conversion between transport message types.
+ */
+export declare class ProtobufFrameSerializer extends FrameSerializer {
+    static readonly SERIALIZABLE_TYPES: ReadonlyMap<AnyCtor, frame_protos.FrameOneofName>;
+    static readonly SERIALIZABLE_FIELDS: ReadonlyMap<frame_protos.FrameOneofName, AnyCtor>;
+    static readonly DESERIALIZABLE_TYPES: ReadonlyMap<ConcreteCtor, frame_protos.FrameOneofName>;
+    static readonly DESERIALIZABLE_FIELDS: ReadonlyMap<string, ConcreteCtor>;
+    /**
+     * Initialize the Protobuf frame serializer.
+     *
+     * @param options.params Configuration parameters.
+     */
+    constructor(options?: FrameSerializerOptions);
+    /**
+     * Serialize a frame to Protocol Buffer binary format.
+     *
+     * @param frame The frame to serialize.
+     * @returns Serialized frame as bytes, or null if frame type is not serializable.
+     */
+    serialize(frame: Frame): Promise<SerializedData | null>;
+    /**
+     * Deserialize Protocol Buffer binary data to a frame.
+     *
+     * @param data Binary protobuf data to deserialize.
+     * @returns Deserialized frame instance, or null if deserialization fails.
+     */
+    deserialize(data: SerializedData): Promise<Frame | null>;
+}
+export {};
+//# sourceMappingURL=protobuf.d.ts.map

package/dist/protobuf.js

@@ -0,0 +1,192 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/serializers/protobuf.py
+/** Protobuf frame serialization for Pipecat. */
+import { rethrowIfCancelled } from "@pipedog/asyncio";
+import { InputAudioRawFrame, InputTransportMessageFrame, InterruptionFrame, OutputAudioRawFrame, OutputTransportMessageFrame, OutputTransportMessageUrgentFrame, TextFrame, TranscriptionFrame, } from "@pipedog/core/frames/frames";
+import * as frame_protos from "@pipedog/core/frames/protobufs/frames_pb2";
+import { FrameSerializer, } from "@pipedog/core/serializers/base_serializer";
+import { logger } from "@pipedog/core/utils/logger";
+import { pyJsonDumps as jsonDumps, pyJsonLoads } from "@pipedog/core/utils/py_json";
+/**
+ * Data class for converting transport messages into Protobuf format.
+ *
+ * - `data`: JSON-encoded message data for transport.
+ */
+export class MessageFrame {
+    data;
+    constructor(options) {
+        this.data = options.data;
+    }
+    toString() {
+        return `MessageFrame(data=${JSON.stringify(this.data)})`;
+    }
+}
+/** Python's truthiness, for the values a frame field can hold. */
+function isTruthy(value) {
+    if (value instanceof Uint8Array) {
+        return value.length > 0;
+    }
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    return Boolean(value);
+}
+/**
+ * Serializer for converting Pipecat frames to/from Protocol Buffer format.
+ *
+ * Provides efficient binary serialization for frame transport over network
+ * connections. Supports text, audio, transcription, and message frames with
+ * automatic conversion between transport message types.
+ */
+export class ProtobufFrameSerializer extends FrameSerializer {
+    static SERIALIZABLE_TYPES = new Map([
+        [TextFrame, "text"],
+        [OutputAudioRawFrame, "audio"],
+        [TranscriptionFrame, "transcription"],
+        [MessageFrame, "message"],
+        [InterruptionFrame, "interruption"],
+    ]);
+    static SERIALIZABLE_FIELDS = new Map([...ProtobufFrameSerializer.SERIALIZABLE_TYPES].map(([k, v]) => [v, k]));
+    static DESERIALIZABLE_TYPES = new Map([
+        [TextFrame, "text"],
+        [InputAudioRawFrame, "audio"],
+        [TranscriptionFrame, "transcription"],
+        [MessageFrame, "message"],
+        [InterruptionFrame, "interruption"],
+    ]);
+    static DESERIALIZABLE_FIELDS = new Map([...ProtobufFrameSerializer.DESERIALIZABLE_TYPES].map(([k, v]) => [v, k]));
+    /**
+     * Initialize the Protobuf frame serializer.
+     *
+     * @param options.params Configuration parameters.
+     */
+    constructor(options = {}) {
+        super(options);
+        // The base serializer defaults to filtering out RTVI protocol messages
+        // to avoid sending them over telephony media streams. ProtobufFrameSerializer
+        // is used by WebSocket transports, which are the delivery channel for
+        // these messages, so we disable the filter.
+        this._params.ignoreRtviMessages = false;
+    }
+    /**
+     * Serialize a frame to Protocol Buffer binary format.
+     *
+     * @param frame The frame to serialize.
+     * @returns Serialized frame as bytes, or null if frame type is not serializable.
+     */
+    async serialize(frame) {
+        // Wrapping this messages as a JSONFrame to send
+        let serializable = frame;
+        if (frame instanceof OutputTransportMessageFrame ||
+            frame instanceof OutputTransportMessageUrgentFrame) {
+            if (this.shouldIgnoreFrame(frame)) {
+                return null;
+            }
+            serializable = new MessageFrame({
+                data: jsonDumps(frame.message),
+            });
+        }
+        const protoFrame = new frame_protos.Frame();
+        const ctor = serializable.constructor;
+        const protoOptionalName = ProtobufFrameSerializer.SERIALIZABLE_TYPES.get(ctor);
+        if (protoOptionalName === undefined) {
+            logger.warning(`Frame type ${ctor.name} is not serializable`);
+            return null;
+        }
+        // As protobuf's `getattr(proto_frame, name)`: the submessage only becomes
+        // the oneof's member once one of its fields is set.
+        const protoField = frame_protos.Frame.DESCRIPTOR.fieldsByName[protoOptionalName];
+        const ProtoType = PROTO_TYPES[protoOptionalName];
+        // Casts: Python sets and reads fields by name with getattr/setattr, genuinely dynamic.
+        const protoAttr = new ProtoType();
+        const source = serializable;
+        let anySet = false;
+        for (const field of protoField?.messageType?.fields ?? []) {
+            if (!(field.attr in source)) {
+                continue;
+            }
+            const value = source[field.attr];
+            if (isTruthy(value)) {
+                protoAttr[field.attr] = value;
+                anySet = true;
+            }
+        }
+        if (anySet) {
+            protoFrame[protoOptionalName] = protoAttr;
+        }
+        return protoFrame.serializeToString();
+    }
+    /**
+     * Deserialize Protocol Buffer binary data to a frame.
+     *
+     * @param data Binary protobuf data to deserialize.
+     * @returns Deserialized frame instance, or null if deserialization fails.
+     */
+    async deserialize(data) {
+        if (typeof data === "string") {
+            // As protobuf's `FromString`, which only accepts bytes.
+            throw new TypeError("a bytes-like object is required, not 'str'");
+        }
+        const proto = frame_protos.Frame.fromString(data);
+        const which = proto.whichOneof("frame");
+        const className = which === null ? undefined : ProtobufFrameSerializer.DESERIALIZABLE_FIELDS.get(which);
+        if (which === null || className === undefined) {
+            logger.error("Unable to deserialize a valid frame");
+            return null;
+        }
+        // Cast: Python reads the oneof member via getattr(proto, which), genuinely dynamic.
+        const args = proto[which];
+        const argsDict = {};
+        for (const field of frame_protos.Frame.DESCRIPTOR.fieldsByName[which]?.messageType?.fields ??
+            []) {
+            argsDict[field.attr] = args[field.attr];
+        }
+        // Remove special fields if needed
+        const id = args.id;
+        const name = args.name;
+        const pts = args.pts;
+        delete argsDict.id;
+        delete argsDict.name;
+        delete argsDict.pts;
+        let instance;
+        // Special handling for MessageFrame -> InputTransportMessageFrame
+        if (className === MessageFrame) {
+            try {
+                const msg = pyJsonLoads(argsDict.data);
+                instance = new InputTransportMessageFrame({ message: msg });
+                logger.debug(`ProtobufFrameSerializer: Transport message ${instance}`);
+            }
+            catch (e) {
+                rethrowIfCancelled(e);
+                logger.error(`Error parsing MessageFrame data: ${e instanceof Error ? e.message : e}`);
+                return null;
+            }
+        }
+        else {
+            // Normal deserialization, create the instance
+            instance = new className(argsDict);
+        }
+        // Set special fields
+        if (id) {
+            instance.id = id;
+        }
+        if (name) {
+            instance.name = name;
+        }
+        if (pts) {
+            instance.pts = pts;
+        }
+        return instance;
+    }
+}
+const PROTO_TYPES = {
+    text: frame_protos.TextFrame,
+    audio: frame_protos.AudioRawFrame,
+    transcription: frame_protos.TranscriptionFrame,
+    message: frame_protos.MessageFrame,
+    interruption: frame_protos.InterruptionFrame,
+};
+//# sourceMappingURL=protobuf.js.map

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@pipedog/serializer-protobuf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Protobuf frame serializer (ProtobufFrameSerializer) for pipedog, wire-compatible with Pipecat's frames.proto.",
+  "license": "BSD-2-Clause",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/polvallverdu/pipedog.git",
+    "directory": "packages/serializer-protobuf"
+  },
+  "homepage": "https://github.com/polvallverdu/pipedog/tree/main/packages/serializer-protobuf#readme",
+  "bugs": {
+    "url": "https://github.com/polvallverdu/pipedog/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@pipedog/asyncio": "0.3.0",
+    "@pipedog/core": "0.3.0"
+  },
+  "pipecat": {
+    "runtimes": [
+      "bun",
+      "node",
+      "deno",
+      "workerd"
+    ],
+    "upstream": [
+      "src/pipecat/serializers/protobuf.py"
+    ]
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}