inv_sig_helper
inv_sig_helper is a Rust service that decrypts YouTube signatures and manages player information. It offers a TCP/Unix socket interface for signature decryption and related operations.
Features
- Decrypt YouTube
nandssignatures - Fetch and update YouTube player data
- Provide signature timestamps and player status
- Efficient signature decryption with multi-threaded JavaScript execution
Run with Docker (recommended method)
A Dockerfile is included for containerized deployment.
And an official Docker image is available at quay.io/invidious/inv-sig-helper: https://quay.io/repository/invidious/inv-sig-helper
Production
Follow the official installation guide: https://github.com/iv-org/documentation/blob/master/docs/installation.md.
Development
Run the project using docker compose:
docker compose up -d
Or you can run it manually but not recommended since you won't lock down the container from potential code execution from Google:
- Build the image:
docker build -t inv_sig_helper .
- Run the container:
docker run -p 127.0.0.1:12999:12999 inv_sig_helper
Building and Running without Docker
Prerequisites
- Rust 1.77 or later
- Cargo
- Patch
- openssl-devel
Building
- Clone the repository and navigate to the project directory:
git clone https://github.com/iv-org/inv_sig_helper.git
cd inv_sig_helper
- Build the project:
cargo build --release
Running
Warning
We recommend running sig_helper inside a locked down environment like an LXC container or a systemd service where only the strict necessary is allowed.
No example outside of Docker have been written for this but feel free to send your contribution.
This service runs untrusted code directly from Google.
Instructions
The service can run in Unix socket mode (default) or TCP mode:
- Unix socket mode:
./target/release/inv_sig_helper_rust
This creates a Unix socket at /tmp/inv_sig_helper.sock.
- TCP mode:
./target/release/inv_sig_helper_rust --tcp [IP:PORT]
If no IP:PORT is given, it defaults to 127.0.0.1:12999.
Protocol Format
All data-types bigger than 1 byte are stored in network endian (big-endian) unless stated otherwise.
Request Base
| Name | Size (bytes) | Description |
|---|---|---|
| opcode | 1 | The operation code to perform, A list of operations currently supported (and their data) can be found in the Operations chapter |
| request_id | 4 | The ID for the current request, Used to distinguish responses in the current connection |
The data afterwards depends on the supplied opcode, Please consult the Operations chapter for more information.
Response Base
| Name | Size (bytes) | Description |
|---|---|---|
| request_id | 4 | The ID for the request that this response is meant for |
| size | 4 | Size of the response (excluding size of request id) |
The data afterwards depends on the supplied opcode, Please consult the Operations chapter for more information.
Operations
FORCE_UPDATE (0x00)
Forces the server to re-fetch the YouTube player, and extract the necessary components from it (nsig function code, sig function code, signature timestamp).
Request
No additional data required
Response
| Name | Size (bytes) | Description |
|---|---|---|
| status | 2 | The status code of the request: 0xF44F if successful, 0xFFFF if no updating is required (YouTube's player ID is equal to the server's current player ID), 0x0000 if an error occurred |
DECRYPT_N_SIGNATURE (0x01)
Decrypt a provided n signature using the server's current nsig function code, and return the result (or an error).
Request
| Name | Size (bytes) | Description |
|---|---|---|
| size | 2 | The size of the encrypted signature |
| string | size |
The encrypted signature |
Response
| Name | Size (bytes) | Description |
|---|---|---|
| size | 2 | The size of the decrypted signature, 0x0000 if an error occurred |
| string | size |
The decrypted signature |
DECRYPT_SIGNATURE (0x02)
Decrypt a provided s signature using the server's current sig function code, and return the result (or an error).
Request
| Name | Size (bytes) | Description |
|---|---|---|
| size | 2 | The size of the encrypted signature |
| string | size |
The encrypted signature |
Response
| Name | Size (bytes) | Description |
|---|---|---|
| size | 2 | The size of the decrypted signature, 0x0000 if an error occurred |
| string | size |
The decrypted signature |
GET_SIGNATURE_TIMESTAMP (0x03)
Get the signature timestamp from the server's current player, and return it in the form of a 64-bit integer. If there's no player, it will return 0 in the timestamp (Please check with PLAYER_STATUS if the server has a player)
Request
No additional data required
Response
| Name | Size (bytes) | Description |
|---|---|---|
| timestamp | 8 | The signature timestamp from the server's current player |
PLAYER_STATUS (0x04)
Get the server's information about the current player.
Request
No additional data required
Response
| Name | Size (bytes) | Description |
|---|---|---|
| has_player | 1 | If the server has a player, this variable will be 0xFF. or else, it will be 0x00 |
| player_id | 4 | The server's current player ID. If the server has no player, this will always be 0x00000000 |
PLAYER_UPDATE_TIMESTAMP (0x05)
Get the time of the last player update, The time is represented as seconds since the last update
Request
No additional data required
Response
| Name | Size (bytes) | Description |
|---|---|---|
| timestamp | 8 | Seconds since the last player update |
License
This project is open source under the AGPL-3.0 license.