> For the complete documentation index, see [llms.txt](https://docs.tvheadend.org/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tvheadend.org/documentation/development/htsp/htsmsg-binary-format.md).

# HTSMSG Binary Format

A message can be of either **map** or **list** type. In a **map** each field has a name, in a **list** the members do not have names, but the order should be preserved.

The field types are:

<table><thead><tr><th width="124">Name </th><th width="70">ID </th><th>Description </th></tr></thead><tbody><tr><td>Map </td><td>1</td><td>Sub message of type map</td></tr><tr><td>S64 </td><td>2</td><td>Signed 64bit integer</td></tr><tr><td>Str </td><td>3</td><td>UTF-8 encoded string</td></tr><tr><td>Bin </td><td>4</td><td>Binary blob</td></tr><tr><td>List </td><td>5</td><td>Sub message of type list</td></tr><tr><td>Dbl</td><td>6</td><td>Double precision floating point</td></tr><tr><td>Bool</td><td>7</td><td>Boolean</td></tr><tr><td>UUID</td><td>8</td><td>64 bit UUID in binary format</td></tr></tbody></table>

All in all the message structure is quite similar to JSON but most notably; no **boolean** nor **null** type exist and HTSMSG supports **binary** objects.

## HTSMSG Binary Format

The binary format is designed to for back-to-back transmission of messages over a network (TCP) connection.

The root message must always be of type **map**.

### Root body

<table data-header-hidden><thead><tr><th width="111"></th><th width="171"></th><th></th></tr></thead><tbody><tr><td>Length</td><td>4 byte integer</td><td>Total length of message (not including this length field itself)</td></tr><tr><td>Body</td><td>HTSMSG-Field * N</td><td>Fields in the root body</td></tr></tbody></table>

### HTSMSG-Field

<table data-header-hidden><thead><tr><th width="146"></th><th width="136"></th><th></th></tr></thead><tbody><tr><td>Type</td><td>1 byte integer</td><td>Type of field (see field type IDs above)</td></tr><tr><td>Namelength</td><td>1 byte integer</td><td>Length of name of field. If a field is part of a list message this must be 0</td></tr><tr><td>Datalength</td><td>4 byte integer</td><td>Length of field data</td></tr><tr><td>Name</td><td>N bytes</td><td>Field name, length as specified by Namelength</td></tr><tr><td>Data</td><td>N bytes</td><td>Field payload, for details see below</td></tr></tbody></table>

#### Field encoding for type: map and list

The data is repeated HTSMSG-Fields exactly as the root body. Note the subtle difference in that for the root-message the length includes the 4 bytes of length field itself whereas in the field encoding the length written includes just the actual payload.

#### Field encoding for type: s64

Integers are encoded using a very simple variable length encoding. All leading bytes that are 0 is discarded. So to encode the value 100, datalength should be 1 and the data itself should be just one byte \[0x64]. To encode 1337; datalength=2, data=\[0x39 0x05].

Note that there is no sign extension in this encoding scheme so if you need to encode -1 you need to set datalength=8 and data = \[0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff]. This can certainly be thought of as a bug, but it is the way it is.

#### Field encoding for type: str

Datalength should be the length of the string (NOT including the null terminating character). Thus the null terminator should not be present in data either.

#### Field encoding for type: bin

Datalength should be the length of the binary object. Data is the binary object itself.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tvheadend.org/documentation/development/htsp/htsmsg-binary-format.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.