Virgil

KO | EN

gitlite — search

#python #hacktoberfest #llm #go #golang #android #machine-learning #docker #windows #cli #kubernetes #pytorch #ios #openai

(★ 10)

An open-source companion protocol to allow for Dante-based preamp control.

Virgil 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Virgil Protocol 2.3.0

Virgil is a network protocol for controlling audio devices using JSON-formatted messages over TCP. It uses mDNS for Virgil Controller and supports real-time parameter control and status monitoring.

While the Virgil Documentation is in progress, virgil version 2.3.0 is finished and will not have any protocol-level changes made. If there are discrepancies in documentation or clarification needed, please create an issue.

**This is Virgil Protocol 2.2.0**

In previous versions of the virgil protocol, devices were categorized in Master/Slave/Server/Client. That no longer exists

# Communication

All networked communication should occur using the UTF-8 encoding.

At the start of every message should be a 4 byte unsigned big endian integer indicating the length of the message in bytes (excluding the integer itself)

TCP sockets should open when the devices connect and only close once one of the devices goes offline

**Watch out for race conditions when managing TCP socket connections.** If two devices attempt to connect simultaneously, ensure your code properly handles conflicting connections.

## TCP Implementation Notes

- Use non-blocking sockets with proper buffering for message reassembly
- Implement proper length-prefixed message framing to handle partial receives
- Handle connection timeouts and disconnections gracefully
- Process complete JSON messages only after receiving the full payload

# mDNS Overview

Virgil uses a typical mDNS configuration. It is advertised over `224.0.0.251` at port `5353`  
The protocol will (almost) fully function on a network that doesn't support mDNS.
mDNS is only used for Virgil Controller.

### Service Configuration
- **serviceType**: `_virgil._tcp_.local.`
- **serviceName**: `{dante name}._virgil._tcp_.local.`
- **txt**
  + **model**: The model of the device (eg. M32)
  + **deviceType**: The type of device it is. For more information and allowed values, go to [Device Types](#device-types)

# Message Types

| Type                | Description                                              | Protocol|
|---------------------|----------------------------------------------------------|---------|
| parameterCommand    | Used to set or change a parameter on a channel           | TCP     |
| statusUpdate        | Used to notify devices of a changed parameter            | TCP     |
| statusRequest       | Used to request a status update for a channel           | TCP     |
| channelLink         | Used to represent that 2 channels are linked in dante    | TCP     |
| channelUnlink       | Used to undo a channelLink                               | TCP     |
| infoRequest		      | Used to request information on a channel                 | TCP	   |
| infoResponse 		    | Used to respond to an infoRequest for a channel         | TCP     |
| deviceInfoRequest   | Used to request device-level information                 | TCP     |
| deviceInfoResponse  | Used to respond to a deviceInfoRequest                   | TCP     |
| errorResponse       | Used to convey an error				                           | TCP     |
| subscribeMessage    | Used to tell a device to inform the sender of any parameter changes for a given channel         | TCP     |
| unsubscribeMessage  | Used to undo a subscribeMessage                          | TCP     |
| endResponse         | Used to say that the sender has no response              | TCP     |

## Message Flow Patterns

### Connection Establishment
1. Device connects via TCP to another device's Virgil port
2. First message should include `transmittingDevice` to identify sender
3. Devices may exchange `deviceInfoRequest`/`deviceInfoResponse` messages for device discovery
4. Devices may exchange `infoRequest`/`infoResponse` messages for channel discovery
5. Channel linking occurs via `channelLink` messages

### Parameter Control Flow
1. Send `parameterCommand` to change a parameter value
2. Receiving device validates the command and updates the parameter
3. Device sends `statusUpdate` to all subscribed devices (except sender)
4. Use `subscribeMessage`/`unsubscribeMessage` to manage subscriptions

### Communication Session Management
- Messages are exchanged in request-response patterns
- Use `endResponse` to indicate end of communication session
- Handle `errorResponse` messages for error conditions
- Maintain connection state and handle disconnections gracefully

### Example with example devices
Device1 has 2 rx and 2 tx, device2 has 2 rx and 2 tx

1. Device1 sends deviceInfoRequest
2. Device2 sends deviceInfoResponse
3. Device1 sends infoRequest for tx 0 and tx 1
4. Device2 sends infoResponse for tx 0 and tx 1
5. Device1 sends channelLink for Device1 rx 0 -> Device2 tx 0 and Device1 rx 1 -> Device2 tx 1
6. Device2 sends statusUpdate for tx 0 and tx 1 because `linkedChannels` was changed
7. Device1 sends statusUpdate for rx 0 and rx 1 because `linkedChannels` was changed
8. Device2 sends deviceInfoRequest
9. Device1 sends deviceInfoResponse
10. Device2 sends infoRequest for tx 0 and tx 1
11. Device1 sends infoResponse for tx 0 and tx 1
12. Device2 sends an endResponse

# Channel Types
There are 3 types of channels represented as integers:

| Integer | Channel Type | Description |
|---------|--------------|-------------|
| 0       | tx           | Transmit channels (Dante transmitting) |
| 1       | rx           | Receive channels (Dante receiving) |
| 2       | aux          | Auxiliary channels (non-Dante accessory channels) |

`tx` (0) and `rx` (1) channels correspond with Dante transmitting and receiving channels. Every dante channel must have a corresponding Virgil channel  
For example, if a dante device had 12 transmitting channels and 8 receiving channels, the device would advertise over virgil that it has 12 `tx` (0) channels and 8 `rx` (1) channels.

tx/rx channels can be linked together to represent the flow of audio via Dante. For more information, go to [Linking Channels](#linking-channels)

Aux channels (2) do not have a Dante equivalent. They are instead used for sending simple values to a device (Think an in-wall dial connected to a mixer)  
Aux channels can be linked to a device, not another channel. For more information, go to [Linking Channels](#linking-channels)

Channel indices start at 0

**Note**: Device-level information is handled separately through `deviceInfoRequest` and `deviceInfoResponse` messages, not through channel types.

## Linking Channels
Channels are linked together to represent the flow of data via Dante. If channels are subscribed in Dante, they must be linked in virgil

Linking to a channel automatically subscribes each device to its corresponding channel.

Rx channels (1) can only be linked to Tx channels (0) and vice versa.

Either side can initiate the link by sending a channelLink.

Aux channels (2) are not linked to another channel. They are instead linked to a device. The linking must be initiated by the device not containing the aux channel.

## Connecting to aux channels
Because Aux channels do not exist in dante, we cannot rely on dante's subscriptions to find where channels are.  
There are several different ways to find aux channel devices
1. Prompt the user for an IP address. A device should always support this in the case a network doesn't allow mDNS
2. Use mDNS to search for virgil devices and allow the user to connect to aux channels
3. Remember previous connections made with methods 1 and 2

# Parameters

Virgil supports various audio parameters. `gain` is mandatory for all channels involving a preamp, even on fixed-gain preamps.

There is also a `linkedChannels` parameter. This is to be treated as any other parameter, but it is mandatory.  
It is an array containing information on what channels are linked to said channel.  
This is an array to account for tx channels being able to be connected to several rx channels in dante.  
`linkedChannels` should start empty and be added to as channels are linked/unlinked

```jsonc
"linkedChannels" : [
  {
    "deviceName" : "connectedDeviceName",
    "channelIndex" : 0, // The connected channel index
    "channelType" : 1 // 0=tx, 1=rx, 2=aux
  },
  {
    "deviceName" : "otherConnectedDevice",
    "channelIndex" : 1, // The connected channel index
    "channelType" : 1 // 0=tx, 1=rx, 2=aux
  },
]
```

If the channel is an aux channel:
```jsonc
"linkedChannels": [
  {
    "deviceName" : "connectedDeviceName"
  }
]
```

### Parameter Structure

Each parameter is a JSON object with the following fields:

- `value`: Current parameter value (only field changeable by servers)
- `dataType`: Data type (`int`, `float`, `bool`, `string`, `enum`)
- `unit` (Required for int/float not readonly): Unit of measurement (e.g., `dB`, `Hz`, `%`)
- `minValue` (Required for int/float not readonly): Minimum allowed value
- `maxValue` (Required for int/float not readonly): Maximum allowed value  
- `precision` (Required for int/float not readonly): Step size
- `readOnly`: If true, parameter cannot be changed
- `enumValues` (enum only): Array of valid string values

### Data Type Notes

- **Locked**: Below, I use the word "locked" often. This means if the control of said parameter is disabled for whatever reason. Don't include a parameter that your device doesn't have
- **Int**: Integer values only. Use for discrete values like channel indices, counts, or settings that don't require decimal precision
- **Float**: Floating-point values. Use for continuous values that may require decimal precision like precise gain adjustments
- **JSON Data Types**: Even though JSON types are only considered `number` and not `int` or `float`, virgil requires you to pre-state the data type of your number to make memory allocation easier.
- **Enum**: Represented as an array of valid string values in `enumValues`
- **Percentage**: Use `%` as unit with `minValue: 0`, `maxValue: 100`, `dataType: "int"` or `"float"`, and appropriate `precision`
- **Precision**: Values increment from `minValue` by `precision` steps (e.g., precision 3dB, minValue -5dB = -5, -2, 1, 4...)

The formula to check if a value is valid is:
```python
isValid = (value - minValue) % precision == 0 and value >= minValue and value <= maxValue
```

Example Enum Parameter:
```jsonc
{
  "transmitPower": {
    "value": "low",
    "enumValues": ["low", "medium", "high"],
    "dataType": "enum",
    "locked": false
  }
}
```

---

## Supported Parameters

### Control Parameters

#### gain (Required)
Analog gain of the channel (independent of pad)
- **unit**: dB
- **dataType**: float (use int if device only supports whole dB increments)
- **minValue**: Device-specific minimum gain
- **maxValue**: Device-specific maximum gain
- **readOnly**: true if gain is fixed or disabled

Example:
```jsonc
"gain" : {
  "unit" : "dB",
  "dataType" : "float",
  "minValue" : -10,
  "maxValue" : 50,
  "value" : 10.5,
  "precision" : 0.1, // Can be higher or lower, depending on your device's precision
  "readOnly" : false 
}
```

Alternative example with integer gain:
```jsonc
"gain" : {
  "unit" : "dB",
  "dataType" : "int",
  "minValue" : -10,
  "maxValue" : 50,
  "value" : 10,
  "precision" : 1,
  "readOnly" : false 
}
```

Alternative example with fixed gain:
```jsonc
"gain" : {
  "unit" : "dB",
  "dataType" : "int",
  "minValue" : 30,
  "maxValue" : 30,
  "precision" : 1,
  "value" : 30,
  "readOnly" : true
}
```

#### pad
Input attenuator control
- **dataType**: bool (true = enabled, false = disabled)
- **readOnly**: true if pad cannot be changed

Example:
```jsonc
"pad" : {
  "dataType" : "bool",
  "value" : false,
  "readOnly" : false
}
```

#### padLevel
The amount enabling the pad lowers the signal
- **dataType**: int (usually negative)
- **unit**: dB
- **readOnly**: Always True (I guess a variable pad is possible, but I've never heard of a preamp with one. Will update if needed)
- **Note**: Required if channel has `pad` variable

Example:
```jsonc
"padLevel" : {
  "dataType" : "int",
  "unit": "dB",
  "value" : -10,
  "readOnly" : true
}
```

#### lowcut
High-pass filter frequency
- **unit**: hz
- **dataType**: int (use float if device supports fractional Hz)
- **minValue**: Device-specific minimum frequency
- **maxValue**: Device-specific maximum frequency
- **precision**: Precision of the frequency selection 
- **readOnly**: true if filter cannot be changed
- **Notes**: Only include this is your device has a physical lowcut circuit. Do not include this if it's a dsp lowcut

Example:
```jsonc
"lowcut" : {
  "dataType" : "int",
  "unit" : "hz",
  "minValue" : 0,
  "maxValue" : 150,
  "precision" : 1,
  "value" : 100,
  "readOnly" : false
}
```

#### lowcutEnable
Enable/disable high-pass filter
- **dataType**: bool (true = enabled, false = disabled)
- **readOnly**: true if control cannot be changed
- **Notes**: If your device has lowcut, it must also have lowcutEnable

Example:
```jsonc
"lowcutEnable" : {
  "dataType" : "bool",
  "value" : true,
  "readOnly" : false
}
```

#### polarity
Signal polarity (phase invert)
- **dataType**: bool (true = inverted, false = normal)
- **readOnly**: true if polarity is locked (Don't include this if your device can't change polarity)

Example:
```jsonc
"polarity" : {
  "dataType" : "bool",
  "value" : true,
  "readOnly" : false
}
```

#### phantomPower
Phantom power control
- **dataType**: bool (true = enabled, false = disabled)
- **readOnly**: true if phantom power is locked

Example:
```jsonc
"phantomPower" : {
  "dataType" : "bool",
  "value" : false,
  "readOnly" : false
}
```

#### rfEnable
RF transmitter/receiver control
- **dataType**: bool (true = enabled, false = disabled)
- **readOnly**: true if RF is locked

Example:
```jsonc
"rfEnable" : {
  "dataType" : "bool",
  "value" : true,
  "readOnly" : false
}
```

#### transmitPower
Transmitter power level (typically for IEM systems)
- **dataType**: enum/int/float
- **unit**: % (only include if dataType is int or float)
- **readOnly**: true if transmit power is locked

Example:
```jsonc
"transmitPower" : {
  "dataType" : "enum",
  "enumValues" : ["low", "medium", "high"],
  "value" : "low",
  "readOnly" : false
}
```

Example with integer percentage:
```jsonc
"transmitPower" : {
  "dataType" : "int",
  "unit" : "%",
  "minValue": 0,
  "maxValue": 100,
  "precision": 1,
  "value" : 100,
  "readOnly" : false
}
```

Example with float percentage:
```jsonc
"transmitPower" : {
  "dataType" : "float",
  "unit" : "%",
  "minValue": 0,
  "maxValue": 100,
  "precision": 0.1,
  "value" : 87.5,
  "readOnly" : false
}
```

#### squelch
Squelch threshold (mutes audio/RF below threshold)
- **unit**: dB or % (device-dependent)
- **dataType**: int or float (depending on device precision)
- **minValue**: Device-specific minimum threshold
- **maxValue**: Device-specific maximum threshold
- **readOnly**: true if squelch is locked

Example with dB (integer):
```jsonc
"squelch" : {
  "dataType" : "int",
  "unit" : "dB",
  "minValue": 30, //I'm sorry, I have no clue what the range would be
  "maxValue": 50,
  "precision": 1,
  "value" : 40,
  "readOnly" : false
}
```

Example with percentage (integer):
```jsonc
"squelch" : {
  "dataType" : "int",
  "unit" : "%",
  "minValue": 0,
  "maxValue": 100,
  "precision": 1,
  "value" : 100,
  "readOnly" : false
}
```

### Status Parameters (Read-Only)

#### deviceConnected
Wireless device connection status
- **dataType**: bool
- **readOnly**: Always true (read-only)

Example:
```jsonc
"deviceConnected" : {
  "dataType" : "bool",
  "value" : false,
  "readOnly" : true
}
```

#### subDevice
Type of device connected to this channel
- **dataType**: string
- **readOnly**: Always true (read-only)
- **Valid Values**: `handheld`, `beltpack`, `gooseneck`, `iem`, `xlr`, `trs`, `disconnected`, `other`

Example:
```jsonc
"subDevice" : {
  "dataType" : "string",
  "value" : "handheld",
  "readOnly" : true
}
```

#### correspondingAux
The index of an aux channel that contains additional parameters that may not be outlined in the spec. 
- **dataType**: int
- **readOnly**: Always true (read-only)
- **Notes**: Value must be between 0 and the amount of aux channels - 1

Example:
```jsonc
"correspondingAux" : {
  "dataType" : "int",
  "value" : 1,
  "readOnly" : true
}
```

### Continuous Parameters (Real-Time Monitoring)
These parameters change frequently and require status updates every 500ms

#### audioLevel
Audio signal level
- **unit**: dBFS
- **dataType**: float (or int if device only reports whole dB values)
- **readOnly**: Always true (read-only)
- **Note**: Because these are read-only, you don't need to provide precision, minValue, or maxValue

audioLevel can be for tx or rx.

Example:
```jsonc
"audioLevel" : {
  "dataType" : "float",
  "unit" : "dBFS",
  "value" : -18.5,
  "readOnly" : true
}
```

#### rfLevel
RF signal strength
- **unit**: dB or %
- **dataType**: int or float (depending on device precision)
- **readOnly**: Always true (read-only)
- **Note**: Because these are read-only, you don't need to provide precision, minValue, or maxValue

Example with dB (integer):
```jsonc
"rfLevel" : {
  "dataType" : "int",
  "unit" : "dB",
  "value" : 40,
  "readOnly" : true
}
```

Example with percentage (integer):
```jsonc
"rfLevel" : {
  "dataType" : "int",
  "unit" : "%",
  "value" : 100,
  "readOnly" : true
}
```

#### batteryLevel
Connected device battery level
- **unit**: %
- **dataType**: int (or float if device reports fractional percentages)
- **readOnly**: Always true (read-only)
- **Note**: Because these are read-only, you don't need to provide precision, minValue, or maxValue

Example:
```jsonc
"batteryLevel" : {
  "dataType" : "int",
  "unit" : "%",
  "value" : 40,
  "readOnly" : true
}
```

### Continuous Parameter Status Update Example
```jsonc
{
  "transmittingDevice": "ClientDanteDeviceName",
  "messages": [
    {
      "messageType": "statusUpdate",
      "channelIndex": 0,
      "channelType": 0, // 0=tx, 1=rx, 2=aux
      "audioLevel": {
        "value": -12.5
      },
      "rfLevel": {
        "value": 85
      },
      "batteryLevel": {
        "value": 67
      }
    }
  ]
}
```

# Device Information

Device information is obtained through `deviceInfoRequest` and `deviceInfoResponse` messages. These are separate from channel-level information and status.

### Device Types
Valid values for the `deviceType` parameter:
- `digitalStageBox`
- `wirelessReceiver`
- `wirelessTransmitter`
- `wirelessCombo`
- `mixer`
- `dsp`
- `computer`
- `controller`
- `other`

### Device-Level Parameters
These parameters are only present in device information responses:

- **model**: Device model name 
- **deviceType**: Device category (string)
- **virgilVersion**: Protocol version being used (string)
- **channelCounts**: The counts for each various types of channels
  - The 3 channel types are 0 (tx), 1 (rx), and 2 (aux)

# Message Details

## Message ID
Every message should contain a unique integer called `messageID`. If the message is in response to another message, you should also include an integer called `responseID` that contains the messageID of the message you are responding to.

### messageID Format
The messageID must follow a specific 12-digit format: ****

- **First 9 digits (HHMMSSmmm)**: Timestamp when the message was sent
  - **HH**: Hour in 24-hour format (00-23)
  - **MM**: Minute (00-59)  
  - **SS**: Second (00-59)
  - **mmm**: Millisecond (000-999)
- **Last 3 digits (###)**: Incrementing counter (000-999) to ensure uniqueness when multiple messages are sent within the same millisecond

**Example**: `143052847000` represents a message sent at 14:30:52.847 (2:30:52.847 PM) and is the 1st message sent in that millisecond.

It is not recommended that this number is used for anything besides logging, as devices may not have synchronized timestamps, particularly Aux devices that are not connected via Dante

endResponses should not have `responseID`

A statusUpdate should only have a `responseID` if you are sending the message to the device that triggered the statusUpdate. There should be no `responseID` if you are sending it because of continuous parameters

### Status Update
A status update can be triggered by 3 events:
1. A parameter was changed via `parameterCommand`
2. Continuous parameters haven't been broadcasted in 500ms
3. A `statusRequest` was received for a channel

In cases 1 and 2, the status update should be sent to all devices subscribed to that channel.
In case 3, the status update should be sent only to the device that requested it.

**Note**: Status updates only include the values that have changed, not the full parameter structure. Status updates are only for channel-level parameters, not device information.

#### Error Types
- `UnrecognizedCommand`: Unknown message type
- `ValueOutOfRange`: Parameter value outside allowed range
- `InvalidValueType`: Wrong data type for parameter
- `UnableToChangeValue`: Parameter cannot be modified currently
- `DeviceNotFound`: Target device not available
- `ChannelIndexInvalid`: Channel does not exist
- `ParameterReadOnly`: Parameter is read-only or disabled
- `ParameterUnsupported`: Parameter not supported by device
- `MalformedMessage`: Invalid JSON or message structure
- `Busy`: Device cannot process request currently
- `Timeout`: Request timed out
- `PermissionDenied`: Insufficient privileges
- `InternalError`: Device internal error
- `OutOfResources`: Device resource exhaustion
- `NetworkError`: Network communication problem
- `Custom:Description`: Custom error (replace Description with specific details)

---

# Implementation Notes

- **Error Handling**: Always provide clear, user-friendly error messages in `errorString`
- **Device Discovery**: Use `deviceInfoRequest`/`deviceInfoResponse` for device-level information discovery
- **Channel Discovery**: Use `infoRequest`/`infoResponse` for channel-level parameter discovery  
- **Status Monitoring**: Use `statusRequest`/`statusUpdate` for channel parameter monitoring
- **Continuous Monitoring**: Implement 500ms update intervals for continuous parameters
- **Network Resilience**: Handle device disconnections and reconnections gracefully
- **Example Files**: Reference the `Example JSON/` directory for complete message examples
- **Network Selection**: All Virgil data should be routed through the same way that your devices Dante control network is routed.

---

# See Also

- Example JSON message files in the `Example JSON/` directory

Virgil

Virgil 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Virgil

Virgil 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README