Volume Offset Control Service

Revision: v1.0

Revision Date: 2020-12-15

Group Prepared By: Generic Audio Working Group

Abstract:

This specification describes the service that exposes the volume offset of an audio output.

Revision History

Revision Number	Date	Comments
v1.0	2020-12-15	Adopted by the Bluetooth SIG Board of Directors.

Contributors

Name	Company
Michael Rougeux	Bose Corporation
Siegfried Lehmann	Apple, Inc.
Tim Reilly	Bose Corporation
Robin Heydon	Qualcomm, Inc.
Asbjørn Sæbø	Nordic Semiconductor ASA
Georg Dickmann	Sonova AG
Bjarne Klemmensen	Oticon A/S
HJ Lee	LG Electronics Inc.
Marcel Holtmann	Intel Corporation
Masahiko Seki	Sony Corporation
Søren Møllskov Larsen	Widex A/S
Daniel Sisolak	Bose Corporation
Oren Haggai	Intel Corporation
Frank Yerrace	Microsoft Corporation

Use of this specification is your acknowledgement that you agree to and will comply with the following notices and disclaimers. You are advised to seek appropriate legal, engineering, and other professional advice regarding the use, interpretation, and effect of this specification.

Use of Bluetooth specifications by members of Bluetooth SIG is governed by the membership and other related agreements between Bluetooth SIG and its members, including those agreements posted on Bluetooth SIG’s website located at www.bluetooth.com. Any use of this specification by a member that is not in compliance with the applicable membership and other related agreements is prohibited and, among other things, may result in (i) termination of the applicable agreements and (ii) liability for infringement of the intellectual property rights of Bluetooth SIG and its members. This specification may provide options, because, for example, some products do not implement every portion of the specification. Each option identified in the specification is intended to be within the bounds of the Scope as defined in the Bluetooth Patent/Copyright License Agreement (“PCLA”). Also, the identification of options for implementing a portion of the specification is intended to provide design flexibility without establishing, for purposes of the PCLA, that any of these options is a “technically reasonable non-infringing alternative.”

Use of this specification by anyone who is not a member of Bluetooth SIG is prohibited and is an infringement of the intellectual property rights of Bluetooth SIG and its members. The furnishing of this specification does not grant any license to any intellectual property of Bluetooth SIG or its members. THIS SPECIFICATION IS PROVIDED “AS IS” AND BLUETOOTH SIG, ITS MEMBERS AND THEIR AFFILIATES MAKE NO REPRESENTATIONS OR WARRANTIES AND DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING ANY WARRANTIES OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT, FITNESS FOR ANY PARTICULAR PURPOSE, OR THAT THE CONTENT OF THIS SPECIFICATION IS FREE OF ERRORS. For the avoidance of doubt, Bluetooth SIG has not made any search or investigation as to third parties that may claim rights in or to any specifications or any intellectual property that may be required to implement any specifications and it disclaims any obligation or duty to do so.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, BLUETOOTH SIG, ITS MEMBERS AND THEIR AFFILIATES DISCLAIM ALL LIABILITY ARISING OUT OF OR RELATING TO USE OF THIS SPECIFICATION AND ANY INFORMATION CONTAINED IN THIS SPECIFICATION, INCLUDING LOST REVENUE, PROFITS, DATA OR PROGRAMS, OR BUSINESS INTERRUPTION, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, AND EVEN IF BLUETOOTH SIG, ITS MEMBERS OR THEIR AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF THE DAMAGES.

Products equipped with Bluetooth wireless technology ("Bluetooth Products") and their combination, operation, use, implementation, and distribution may be subject to regulatory controls under the laws and regulations of numerous countries that regulate products that use wireless non-licensed spectrum. Examples include airline regulations, telecommunications regulations, technology transfer controls, and health and safety regulations. You are solely responsible for complying with all applicable laws and regulations and for obtaining any and all required authorizations, permits, or licenses in connection with your use of this specification and development, manufacture, and distribution of Bluetooth Products. Nothing in this specification provides any information or assistance in connection with complying with applicable laws or regulations or obtaining required authorizations, permits, or licenses.

Bluetooth SIG is not required to adopt any specification or portion thereof. If this specification is not the final version adopted by Bluetooth SIG’s Board of Directors, it may not be adopted. Any specification adopted by Bluetooth SIG’s Board of Directors may be withdrawn, replaced, or modified at any time. Bluetooth SIG reserves the right to change or alter final specifications in accordance with its membership and operating agreements.

Copyright © 2018–2020. All copyrights in the Bluetooth Specifications themselves are owned by Apple Inc., Ericsson AB, Intel Corporation, Lenovo (Singapore) Pte. Ltd., Microsoft Corporation, Nokia Corporation, and Toshiba Corporation. The Bluetooth word mark and logos are owned by Bluetooth SIG, Inc. Other third-party brands and names are the property of their respective owners.

1. Introduction

This service enables a device to expose the volume offset of an audio output.

1.1. Conformance

If conformance to this specification is claimed, all capabilities indicated as mandatory for this specification shall be supported in the specified manner (process-mandatory). This also applies for all optional and conditional capabilities for which support is indicated.

1.2. Service dependencies

This service is not dependent upon any other services.

1.3. Bluetooth Core Specification release compatibility

This specification is compatible with any version of the Bluetooth Core Specification [1] that includes the Generic Attribute Profile (GATT).

1.4. GATT sub-procedure requirements

Requirements in this section represent a minimum set of server requirements. Other GATT sub‑procedures may be used if supported by both the client and server.

Requirements in this section are defined as “Mandatory” (M), “Optional” (O), “Excluded” (X), and “Conditional” (C.n). Conditional statements (C.n) are listed directly below the table in which they appear.

Table 1.1 summarizes additional GATT sub-procedure requirements beyond those required by all GATT servers over Unenhanced Attribute Protocol (ATT) bearers.

GATT Sub-Procedure	Requirements
Write Characteristic Values	M
Notifications	M
Read Characteristic Descriptors	M
Write Characteristic Descriptors	M

Table 1. Table 1.1: GATT sub-procedure requirements, Unenhanced ATT bearers

1.5. Transport dependencies

This service uses GATT and therefore has no additional transport dependencies.

Notifications with GATT are considered unreliable when used with an Unenhanced ATT bearer.

An Enhanced ATT bearer can be used for reliability of Notifications and can be specified by a higher-layer profile.

1.6. Application error codes

This service defines the ATT Application Error code shown in Table 1.2.

Name	Error Code	Description
Invalid Change Counter	0x80	The Change_Counter operand value does not match the Change_Counter field value of the Volume Offset State characteristic.
Opcode Not Supported	0x81	An invalid opcode has been used in a control point procedure.
Value Out of Range	0x82	An operand value used in a control point procedure is outside the permissible range.

Table 2. Table 1.2: Application error codes

1.7. Byte transmission order

All characteristics used with this service shall be transmitted with the least significant octet (LSO) first (i.e., little endian). The LSO is identified in the characteristic definitions in the Bluetooth SIG Assigned Numbers [3].

1.8. Language

1.8.1. Language conventions

The Bluetooth SIG has established the following conventions for use of the words shall, must, will, should, may, can, is, and note in the development of specifications:

shall	is required to – used to define requirements.
must	is used to express: a natural consequence of a previously stated mandatory requirement. OR an indisputable statement of fact (one that is always true regardless of the circumstances).
will	it is true that – only used in statements of fact.
should	is recommended that – used to indicate that among several possibilities one is recommended as particularly suitable, but not required.
may	is permitted to – used to allow options.
can	is able to – used to relate statements in a causal manner.
is	is defined as – used to further explain elements that are previously required or allowed.
note	Used to indicate text that is included for informational purposes only and is not required in order to implement the specification. Each note is clearly designated as a “Note” and set off in a separate paragraph.

For clarity of the definition of those terms, see Core Specification Volume 1, Part E, Section 1.

1.8.2. Reserved for Future Use

Where a field in a packet, Protocol Data Unit (PDU), or other data structure is described as "Reserved for Future Use" (irrespective of whether in uppercase or lowercase), the device creating the structure shall set its value to zero unless otherwise specified. Any device receiving or interpreting the structure shall ignore that field; in particular, it shall not reject the structure because of the value of the field.

Where a field, parameter, or other variable object can take a range of values, and some values are described as "Reserved for Future Use," a device sending the object shall not set the object to those values. A device receiving an object with such a value should reject it, and any data structure containing it, as being erroneous; however, this does not apply in a context where the object is described as being ignored or it is specified to ignore unrecognized values.

When a field value is a bit field, unassigned bits can be marked as Reserved for Future Use and shall be set to 0. Implementations that receive a message that contains a Reserved for Future Use bit that is set to 1 shall process the message as if that bit was set to 0, except where specified otherwise.

The acronym RFU is equivalent to Reserved for Future Use.

1.8.3. Prohibited

When a field value is an enumeration, unassigned values can be marked as “Prohibited.” These values shall never be used by an implementation, and any message received that includes a Prohibited value shall be ignored and shall not be processed and shall not be responded to.

Where a field, parameter, or other variable object can take a range of values, and some values are described as “Prohibited,” devices shall not set the object to any of those Prohibited values. A device receiving an object with such a value should reject it, and any data structure containing it, as being erroneous.

“Prohibited” is never abbreviated.

1.8.4. Terminology

Table 1.3 defines terms that are needed to understand features used in this service.

Term	Definition
Unenhanced ATT bearer	An ATT bearer not using the Enhanced Credit Based Flow Control Logical Link Control and Adaptation Protocol (L2CAP) channel mode introduced in Volume 3, Part A, Section 10.2 in the Bluetooth Core Specification [2].
Enhanced ATT bearer	An ATT bearer using the Enhanced Credit Based Flow Control L2CAP channel mode introduced in Volume 3, Part A, Section 10.2 in [2].

Table 3. Table 1.3: Terminology

2. Service

2.1. Declaration

There may be one or more instances of the Volume Offset Control Service (VOCS) on a device.

VOCS is instantiated to expose the offset level and location of an audio output such as a speaker.

The Attribute Type service declaration shall be set to the «Secondary Service» universally unique identifier (UUID) and the Attribute Value service declaration shall be set to «Volume Offset Control Service» as defined in the Bluetooth SIG Assigned Numbers [3]. VOCS shall only be instantiated as an included service.

2.2. Overview

This section provides an overview of the behavior and usage of the characteristics that affect the audio output’s offset.

2.2.1. Volume Offset State

The Volume Offset State characteristic value consists of two fields: the Volume_Offset and Change_Counter fields.

2.2.1.1. Volume_Offset field

The Volume_Offset field value controls the offset of an individual audio output that the server controls, such as a left or right speaker. The Volume_Offset field may be used to apply balance or other leveling.

The Volume_Offset field is a unitless value and is added to the audio output’s volume, such that a positive Volume_Offset value results in an increase of the audio output volume and a negative Volume_Offset value results in a decrease of the audio output volume.

2.2.1.2. Change_Counter field

The server shall increment the Change_Counter field value by one upon every change to the Volume_Offset field value. The Change_Counter field value is used in all Volume Offset Control Point commands.

The server shall initialize the Change_Counter field to an arbitrary value. The value shall be in the range of 0 to 255. An increment past 255 shall roll over to 0.

3. Service characteristics

This section defines the characteristic and descriptor requirements.

Characteristic Name	Requirement	Mandatory Properties	Optional Properties	Security Permissions
Volume Offset State	M	Read, Notify	None	Encryption Required
Audio Location	M	Read, Notify [C.1]	Write Without Response, Notify	Encryption Required
Volume Offset Control Point	M	Write	None	Encryption Required
Audio Output Description	M	Read, Notify [C.1]	Write Without Response, Notify	Encryption Required

Table 4. Table 3.1: VOCS characteristics

C.1: Mandatory to support Notify if Write Without Response is supported, otherwise Optional.

Properties not listed as Mandatory or Optional in Table 3.1 are Excluded.

3.1. Volume Offset State

The Volume Offset State characteristic shall be used to reflect the state of the audio volume to which this service applies. The value of the Volume Offset State characteristic shall use the format described in Table 3.2.

Field Name	Size (Octets)	Format
Volume_Offset	2	int16
Change_Counter	1	uint8

Table 5. Table 3.2: Volume Offset State characteristic value format

3.1.1. Volume_Offset field

The Volume_Offset field shall be set to a value that reflects the current offset that is applied to the volume of the audio output to which this service applies. This value might be used, for example, to apply a balance between left and right audio channels on the same device or an offset among many devices.

The Volume_Offset field is applied as described in Section 2.2.1.1.

3.1.2. Change_Counter field

The server shall initialize the Change_Counter field to an arbitrary value. The Change_Counter field value shall be incremented by 1 when the Volume_Offset field value changes and shall not be changed otherwise. When the Change_Counter field value reaches 255, its next increment shall be 0.

3.1.3. Volume Offset State behavior

The Volume Offset State characteristic value may be read by the client. When the Volume Offset State value changes, the server shall notify clients that have enabled the Client Characteristic Configuration Descriptor for notifications of the new value. The Volume Offset State characteristic value shall be the same for all clients.

3.2. Audio Location

The Audio Location characteristic value is a bitmask that shall be set to a value that reflects the location of an audio output that is associated with the instance of VOCS, such as Left or Right. For example, a server might have both a left and right speaker with which to control the balance. In this example, the server should instantiate VOCS for each speaker. The client may use this value to inform the user about the server audio. The Audio Location characteristic value is defined in the Bluetooth Assigned Numbers [3].

3.2.1. Audio Location behavior

The Audio Location characteristic value may be read and optionally written by the client. When the Audio Location value changes, the server shall notify clients that have enabled the Client Characteristic Configuration Descriptor for notifications of the new value if the server supports notifications of this characteristic.

3.3. Volume Offset Control Point

The Volume Offset Control Point characteristic is used to request a specific procedure to be executed by the server when a value is written to it.

3.3.1. Volume Offset Control Point procedure requirements

Table 3.3 lists the requirements for the Volume Offset Control Point procedures for the request opcodes and operands in the context of this VOCS.

Opcode Value	Opcode	Procedure Section	Opcode Requirement	Operand
0x01	Set Volume Offset	Section 3.3.2.1	M	Change_Counter, Volume_Offset

Table 6. Table 3.3: Volume Offset Control Point procedure requirements

3.3.2. Volume Offset Control Point behavior

The Volume Offset Control Point characteristic value may be written by the client.

If a client writes an opcode that is not supported or not defined in Table 3.3, then the server shall return an ATT Error Response with the error code Opcode Not Supported defined in Table 1.2.

If the control point procedure includes the Change_Counter field, and a client writes a Change_Counter operand that does not equal the Change_Counter field of the Volume Offset State characteristic value, then the server shall return an ATT Error Response with the error code Invalid Change Counter defined in Table 1.2.

3.3.2.1. Set Volume Offset procedure

If the Set Volume Offset opcode is written to the Volume Offset Control Point characteristic and the Change_Counter operand matches the Change_Counter field of the Volume Offset State characteristic value, then the server shall set the Volume_Offset field value to the Volume_Offset operand value. If the Set Volume Offset procedure causes the Volume_Offset field value to change, the server shall notify clients of the new Volume Offset State value, as described in Section 3.1.3.

If the Volume operand value is less than -255 or greater than 255, then the server shall return an ATT Error Response with the error code Value Out of Range defined in Table 1.2.

The Volume Offset Control Point characteristic value used for the Set Volume Offset procedure shall be formatted as listed in Table 3.4.

Parameter	Size (Octets)	Value
Opcode	1	0x01 = Set Volume Offset Opcode
Change_Counter	1	0x00–0xFF
Volume_Offset	2	-255 to 255

Table 7. Table 3.4: Set Volume Offset format

3.4. Audio Output Description

The Audio Output Description characteristic shall be set to a description of the audio output that the VOCS instance describes, for example “Left Speaker” or “Right Warehouse Speaker.” The characteristic value is a UTF-8 string of zero or more characters.

3.4.1. Audio Output Description behavior

The Audio Output Description characteristic value may be read and optionally written by the client. When the Audio Output Description value changes, the server shall notify clients that have enabled the Client Characteristic Configuration Descriptor for notifications of the new value if the server supports notifications of this characteristic.

4. SDP interoperability

If VOCS is exposed over Basic Rate/Enhanced Data Rate (BR/EDR), then the service shall have the Service Discovery Protocol (SDP) record defined in Table 4.1.

Item	Definition	Type	Value	Status
Service Class ID List	–	–	–	M
Service Class #0	–	UUID	«Volume Offset Control Service»	M
Protocol Descriptor List	–	Data Element Sequence	–	M
Protocol #0	–	UUID	«L2CAP»	M
Parameter #0 for Protocol #0	Protocol/Service Multiplexer (PSM)	uint16	PSM = ATT	M
Protocol #1	–	UUID	«ATT»	M
Additional Protocol Descriptor List	–	Data Element Sequence	–	C.1
Protocol Descriptor List	–	Data Element Sequence	–	C.1
Protocol #0	–	UUID	«L2CAP»	C.1
Parameter #0 for Protocol #0	PSM	uint16	PSM = EATT	C.1
Protocol #1	–	UUID	«ATT»	C.1
BrowseGroupList	–	–	PublicBrowseRoot Other browse UUIDs may also be included in the list.	M

Table 8. Table 4.1: SDP record

C.1: Mandatory if Enhanced Attribute Protocol (EATT), introduced in Volume 3, Part F, Section 3.2.11 in [2], is supported, otherwise Excluded.

5. Acronyms and abbreviations

Acronym/Abbreviation	Meaning
ATT	Attribute Protocol
BR/EDR	Basic Rate/Enhanced Data Rate
EATT	Enhanced Attribute Protocol
GATT	Generic Attribute Profile
L2CAP	Logical Link Control and Adaptation Protocol
LSO	least significant octet
PDU	Protocol Data Unit
PSM	Protocol/Service Multiplexer
RFU	Reserved for Future Use
SDP	Service Discovery Protocol
UUID	universally unique identifier
VOCS	Volume Offset Control Service

Table 9. Table 5.1: Acronyms and abbreviations

6. References

[1] Bluetooth Core Specification, Version 4.0 or later

[2] Bluetooth Core Specification, Version 5.2

[3] Bluetooth SIG Assigned Numbers, https://www.bluetooth.com/specifications/assigned-numbers