add compressed_payload field to both RpcRequest and RpcResponse by xianshijing-lk · Pull Request #1403 · livekit/protocol

xianshijing-lk · 2026-02-06T22:49:35Z

So that we don't need to use base64 to encode the string, which adds 33% of overhead

changeset-bot · 2026-02-06T22:49:39Z

⚠️ No Changeset found

Latest commit: 8a1d7a8

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

💥 An error occurred when fetching the changed packages and changesets in this PR

Some errors occurred when validating the changesets config:
The package or glob expression "github.com/livekit/protocol" specified in the `fixed` option does not match any package in the project. You may have misspelled the package name or provided an invalid glob expression. Note that glob expressions must be defined according to https://www.npmjs.com/package/micromatch.

boks1971 · 2026-02-07T07:22:52Z

protobufs/livekit_models.proto

  uint32 response_timeout_ms = 4;
  uint32 version = 5;
+  // Compressed payload data. When set, this field is used instead of `payload`.
+  bytes compressed_payload = 6;


Is an alternative a possible consideration? A field like

enum Encoding { BASE64 = 0; --> to ensure default remains the same COMPRESSION_TYPE_1 = 1; COMPRESSION_TYPE_2 = 2; }

This allows an extensible format and we can have any encoding.

+1 for this suggestion

GZIP will the only one available on all platforms. I actually don't see opportunity that we will support the second compression in the near term.

And when it gets to adding supported compression type, we might want to do it in the ParticipantInfo, similar to client_protocol, so that we don't need to embed the same values with every RPC, even though it might just be 2 bytes; another reason is that if some compression is not supported on some platforms, we will need to negotiate the compression before the 1st RPC msg.

What do you think ? I am OK with adding it if you feel strong about it, otherwise we will just keep it simple for now, and will do it properly when we are adding another compression.

xianshijing-lk · 2026-02-10T15:43:42Z

A gentle ping, what do you think about the comment ? I am open to adding an enum, but would like to get confirmation we want to do it with this PR now

boks1971 · 2026-02-10T16:18:37Z

A gentle ping, what do you think about the comment ? I am open to adding an enum, but would like to get confirmation we want to do it with this PR now

Not sure who you were addressing to @xianshijing-lk . I think an enum in this PR would be great. Doing one version with compressed_bytes and changing again later to an enum seems to me would make life more difficult down the line.

xianshijing-lk · 2026-02-12T21:49:03Z

added RpcPayloadType enum there, please take another look. Thanks

boks1971 · 2026-02-13T04:56:16Z

protobufs/livekit_models.proto

  bool generated = 6; // true if the chat message has been generated by an agent from a participant's audio transcription
 }

+enum RpcPayloadType {


suggestion: rename to RpcPayloadEncoding and the UNCOMPRESSED part could be renamed to BASE64 if we are using BASE64. Encoding I think is a better name as it annotates the data format.

I think there are some confusion here.

Today, we have "string payload", which can be used to send texts without compression.
It can't be as compressed_payload unless we use base64 to encode to compressed data, but base64 will add 33% overhead on the payload size.

To your question regarding BASE64, no, base64 should not be used, and we are trying to avoid it by adding a dedicated bytes compressed_payload;

RpcPayloadEncoding can be a wrong name, unless you change it to something like
{
NONE,
GZIP,
}
but I think RpcPayloadType is more telling, since it tells the type of payload, is it uncompressed or gizp compressed ?

If we go with a bytes field, I guess UTF8 would make sense as the default.

boks1971 · 2026-02-13T04:57:37Z

protobufs/livekit_models.proto

  uint32 version = 5;
+  // Compressed payload data. When set, this field is used instead of `payload`.
+  bytes compressed_payload = 6;
+  // Indicates the compression type used for compressed_payload.


Do we need a compressed_payload separate field? I was think this field would tell what encoding is used for payload field.

Yes, it is a must unless we use base64 to encode the compress data, but that will seriously hurt the performance.

the challenge I think is that the original field is a string and I guess we'd want bytes now.

🤦 I missed that. Sorry.

Okay, a new field is needed.

Naming suggestion then

encoded_payload

Rename enum to RpcPayloadEncoding

I think the naming of Encoding is more generic and can be used irrespective of whether the data is compressed or not.

I usually don't have much strong opinion on the naming, but just think encoding != compression.

From chatgpt:
Is encoding the right term for compression?

Not really. Compression is not usually called encoding.

Encoding = changing representation so data can be transported/stored safely
Examples: UTF-8, Base64, JSON, Protobuf

Compression = reducing size by applying an algorithm
Examples: GZIP, Brotli, Zstd

So if your enum values are:

UNCOMPRESSED

GZIP

…then what you’re describing is compression, not encoding.

So what’s the best name?

Here are the most accurate options:

✅ RpcPayloadCompression

NONE

GZIP

This is the clearest and most semantically correct.

✅ RpcPayloadFormat or RpcPayloadRepresentation
If the enum is also indicating which field is populated (text vs binary).

⚠️ RpcPayloadEncoding
Only makes sense if you include things like BASE64, UTF8, etc.
But in your case, payload is plain text already — so “encoding” becomes confusing.

Would RpcPayloadFormat or RpcPayloadCompression work better ?

I think based on this and other discussions, we can probably go with the following

compressed_payload field

As it is always going to be GZIP, we can drop the payload type/format field and ad it later if needed.

If we need the payload type/format and have several options, my preference would be to put it in RPC messages rather than ParticipantInfo as each RPC message could be compressed differently based on content type, etc.

boks1971 · 2026-02-13T04:58:33Z

protobufs/livekit_models.proto

+    bytes compressed_payload = 4;
  }
+  // Indicates the compression type used for compressed_payload.
+  RpcPayloadType payload_type = 5;


same comment as above.

xianshijing-lk · 2026-02-09T23:19:45Z

protobufs/livekit_models.proto

  uint32 response_timeout_ms = 4;
  uint32 version = 5;
+  // Compressed payload data. When set, this field is used instead of `payload`.
+  bytes compressed_payload = 6;


GZIP will the only one available on all platforms. I actually don't see opportunity that we will support the second compression in the near term.

And when it gets to adding supported compression type, we might want to do it in the ParticipantInfo, similar to client_protocol, so that we don't need to embed the same values with every RPC, even though it might just be 2 bytes; another reason is that if some compression is not supported on some platforms, we will need to negotiate the compression before the 1st RPC msg.

What do you think ? I am OK with adding it if you feel strong about it, otherwise we will just keep it simple for now, and will do it properly when we are adding another compression.

xianshijing-lk · 2026-02-13T05:09:55Z

protobufs/livekit_models.proto

  bool generated = 6; // true if the chat message has been generated by an agent from a participant's audio transcription
 }

+enum RpcPayloadType {


I think there are some confusion here.

Today, we have "string payload", which can be used to send texts without compression.
It can't be as compressed_payload unless we use base64 to encode to compressed data, but base64 will add 33% overhead on the payload size.

To your question regarding BASE64, no, base64 should not be used, and we are trying to avoid it by adding a dedicated bytes compressed_payload;

RpcPayloadEncoding can be a wrong name, unless you change it to something like
{
NONE,
GZIP,
}
but I think RpcPayloadType is more telling, since it tells the type of payload, is it uncompressed or gizp compressed ?

xianshijing-lk · 2026-02-13T05:10:57Z

protobufs/livekit_models.proto

  uint32 version = 5;
+  // Compressed payload data. When set, this field is used instead of `payload`.
+  bytes compressed_payload = 6;
+  // Indicates the compression type used for compressed_payload.


Yes, it is a must unless we use base64 to encode the compress data, but that will seriously hurt the performance.

xianshijing-lk · 2026-02-13T06:44:15Z

protobufs/livekit_models.proto

  uint32 version = 5;
+  // Compressed payload data. When set, this field is used instead of `payload`.
+  bytes compressed_payload = 6;
+  // Indicates the compression type used for compressed_payload.


I usually don't have much strong opinion on the naming, but just think encoding != compression.

From chatgpt:
Is encoding the right term for compression?

Not really. Compression is not usually called encoding.

Encoding = changing representation so data can be transported/stored safely
Examples: UTF-8, Base64, JSON, Protobuf

Compression = reducing size by applying an algorithm
Examples: GZIP, Brotli, Zstd

So if your enum values are:

UNCOMPRESSED

GZIP

…then what you’re describing is compression, not encoding.

So what’s the best name?

Here are the most accurate options:

✅ RpcPayloadCompression

NONE

GZIP

This is the clearest and most semantically correct.

✅ RpcPayloadFormat or RpcPayloadRepresentation
If the enum is also indicating which field is populated (text vs binary).

⚠️ RpcPayloadEncoding
Only makes sense if you include things like BASE64, UTF8, etc.
But in your case, payload is plain text already — so “encoding” becomes confusing.

Would RpcPayloadFormat or RpcPayloadCompression work better ?

xianshijing-lk · 2026-02-13T22:32:06Z

protobufs/livekit_models.proto


+enum RpcPayloadFormat {
+  RPF_UNKNOWN = 0;
+  RPF_GZIP = 1;


FYI, proto3 will have default value as 0, thus we'd better not use 0 for GZIP.

And since RpcPayloadFormat is also a top level enum in the same package, using just UNKNOWN would conflict with TrackSource.UNKNOWN.

Thus we need to add a prefix, RPF_ (abbreviation for RpcPayloadFormat) to avoid this collision.

That is the same for enum ReconnectReason {
RR_UNKNOWN = 0;
RR_SIGNAL_DISCONNECTED = 1;
RR_PUBLISHER_FAILED = 2;
RR_SUBSCRIBER_FAILED = 3;
RR_SWITCH_CANDIDATE = 4;
}

xianshijing-lk requested review from boks1971 and lukasIO February 6, 2026 22:49

boks1971 reviewed Feb 7, 2026

View reviewed changes

xianshijing-lk force-pushed the sxian/CLT-2533/add_compressed_payload_field branch from 840ee54 to e1f730b Compare February 12, 2026 21:47

boks1971 reviewed Feb 13, 2026

View reviewed changes

xianshijing-lk and others added 4 commits February 13, 2026 14:29

add compressed_payload field to both RpcRequest and RpcResponse

6c9eb95

adding RpcPayloadType enum

bc0b39a

generated protobuf

30eeeaa

addressed the comments

1769510

xianshijing-lk force-pushed the sxian/CLT-2533/add_compressed_payload_field branch from 6509cc8 to 1769510 Compare February 13, 2026 22:29

generated protobuf

8a1d7a8

xianshijing-lk commented Feb 13, 2026

View reviewed changes

Conversation

xianshijing-lk commented Feb 6, 2026

Uh oh!

changeset-bot bot commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xianshijing-lk commented Feb 10, 2026

Uh oh!

boks1971 commented Feb 10, 2026

Uh oh!

xianshijing-lk commented Feb 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

changeset-bot bot commented Feb 6, 2026 •

edited

Loading