RFC 6295
RTP Payload Format for MIDI
Appendix A. The Recovery Journal Channel Chapters
A.1. Recovery Journal Definitions
This appendix defines the terminology and the coding idioms that are used in the recovery journal bitfield descriptions in Section 5 (journal header structure), Appendices A.2 to A.9 (channel journal chapters), and Appendices B.1 to B.5 (system journal chapters). We assume that the recovery journal resides in the journal section of an RTP packet with sequence number I ("packet I") and that the Checkpoint Packet Seqnum field in the top-level recovery journal header refers to a previous packet with sequence number C (an exception is the self-referential C = I case). Unless stated otherwise, algorithms are assumed to use modulo 2^16 arithmetic for calculations on 16-bit sequence numbers and modulo 2^32 arithmetic for calculations on 32-bit extended sequence numbers. Several bitfield coding idioms appear throughout the recovery journal system with consistent semantics. Most recovery journal elements begin with an "S" (Single-packet loss) bit. S bits are designed to help receivers efficiently parse through the recovery journal hierarchy in the common case of the loss of a single packet. As a rule, S bits MUST be set to 1. However, an exception applies if a recovery journal element in packet I encodes data about a command stored in the MIDI command section of packet I - 1. In this case, the S bit of the recovery journal element MUST be set to 0. If a recovery journal element has its S bit set to 0, all higher-level recovery journal elements that contain it MUST also have S bits that are set to 0, including the top-level recovery journal header. Other consistent bitfield coding idioms are described below: o R flag bit. R flag bits are reserved for future use. Senders MUST set R bits to 0. Receivers MUST ignore R bit values. o LENGTH field. All fields named LENGTH (as distinct from LEN) code the number of octets in the structure that contains it, including the header it resides in and all hierarchical levels below it. If a structure contains a LENGTH field, a receiver MUST use the LENGTH field value to advance past the structure during parsing, rather than use knowledge about the internal format of the structure.
We now define normative terms used to describe recovery journal
semantics.
o Checkpoint history. The checkpoint history of a recovery journal
is the concatenation of the MIDI command sections of packets C
through I - 1. The final command in the MIDI command section for
packet I - 1 is considered the most recent command; the first
command in the MIDI command section for packet C is the oldest
command. If command X is less recent than command Y, X is
considered to be "before Y". A checkpoint history with no
commands is considered to be empty. The checkpoint history never
contains the MIDI command section of packet I (the packet
containing the recovery journal), so if C == I, the checkpoint
history is empty by definition.
o Session history. The session history of a recovery journal is the
concatenation of MIDI command sections from the first packet of
the session up to packet I - 1. The definitions of command
recency and history emptiness follow those in the checkpoint
history. The session history never contains the MIDI command
section of packet I, so the session history of the first packet in
the session is empty by definition.
o Finished/unfinished commands. If all octets of a MIDI command
appear in the session history, the command is defined as being
finished. If some but not all octets of a command appear in the
session history, the command is defined as being unfinished.
Unfinished commands occur if segments of a SysEx command appear in
several RTP packets. For example, if a SysEx command is coded as
3 segments, with segment 1 in packet K, segment 2 in packet K + 1,
and segment 3 in packet K + 2, the session histories for packets K
+ 1 and K + 2 contain unfinished versions of the command. A
session history contains a finished version of a cancelled SysEx
command if the history contains the cancel sublist for the
command.
o Reset State commands. Reset State (RS) commands reset renderers
to an initialized "powerup" condition. The RS commands are System
Reset (0xFF), General MIDI System Enable (0xF0 0x7E 0xcc 0x09 0x01
0xF7), General MIDI 2 System Enable (0xF0 0x7E 0xcc 0x09 0x03
0xF7), General MIDI System Disable (0xF0 0x7E 0xcc 0x09 0x00
0xF7), Turn DLS On (0xF0 0x7E 0xcc 0x0A 0x01 0xF7), and Turn DLS
Off (0xF0 0x7E 0xcc 0x0A 0x02 0xF7). Registrations of subrender
parameter token values (Appendix C.6.2) and IETF Standards-Track
documents MAY specify additional RS commands.
o Active commands. Active commands are MIDI commands that do not
appear before a Reset State command in the session history.
o N-active commands. N-active commands are MIDI commands that do
not appear before one of the following commands in the session
history: MIDI Control Change numbers 123-127 (numbers with All
Notes Off semantics) or 120 (All Sound Off), and any Reset State
command.
o C-active commands. C-active commands are MIDI commands that do
not appear before one of the following commands in the session
history: MIDI Control Change number 121 (Reset All Controllers)
and any Reset State command.
o Oldest-first ordering rule. Several recovery journal chapters
contain a list of elements, where each element is associated with
a MIDI command that appears in the session history. In most
cases, the chapter definition requires that list elements be
ordered in accordance with the "oldest-first ordering rule".
Below, we normatively define this rule.
Elements associated with the most recent command in the session
history coded in the list MUST appear at the end of the list.
Elements associated with the oldest command in the session history
coded in the list MUST appear at the start of the list.
All other list elements MUST be arranged with respect to these
boundary elements, to produce a list ordering that strictly
reflects the relative session history recency of the commands
coded by the elements in the list.
o Parameter system. A MIDI feature that provides two sets of 16,384
parameters to expand the 0-127 controller number space. The
Registered Parameter Numbers (RPN) system and the Non-Registered
Parameter Numbers (NRPN) system each provide 16,384 parameters.
o Parameter system transaction. RPN and NRPN values are changed by
a series of Control Change commands that form a parameter system
transaction. A canonical transaction begins with two Control
Change commands to set the parameter number (controller numbers 99
and 98 for NRPN parameters, controller numbers 101 and 100 for RPN
parameters). The transaction continues with an arbitrary number
of Data Entry (controller numbers 6 and 38), Data Increment
(controller number 96), and Data Decrement (controller number 97)
Control Change commands to set the parameter value. The
transaction ends with a second pair of (99, 98) or (101, 100)
Control Change commands that specify the null parameter (Most
Significant Bit (MSB) value 0x7F, Least Significant Bit (LSB)
value 0x7F).
Several variants of the canonical transaction sequence are
possible. Most commonly, the terminal pair of (99, 98) or (101,
100) Control Change commands may specify a parameter other than
the null parameter. In this case, the command pair terminates the
first transaction and starts a second transaction. The command
pair is considered to be a part of both transactions. This
variant is legal and recommended in [MIDI]. We refer to this
variant as a "type 1 variant".
Less commonly, the MSB (99 or 101) or LSB (98 or 100) command of a
(99, 98) or (101, 100) Control Change pair may be omitted.
If the MSB command is omitted, the transaction uses the MSB value
of the most recent C-active Control Change command for controller
number 99 or 101 that appears in the session history. We refer to
this variant as a "type 2 variant".
If the LSB command is omitted, the LSB value 0x00 is assumed. We
refer to this variant as a "type 3 variant". The type 2 and type
3 variants are defined as legal but are not recommended in [MIDI].
System Real-Time commands may appear at any point during a
transaction (even between octets of individual commands in the
transaction). More generally, [MIDI] does not forbid the
appearance of unrelated MIDI commands during an open transaction.
As a rule, these commands are considered to be "outside" the
transaction and do not affect the status of the transaction in any
way. Exceptions to this rule are commands whose semantics act to
terminate transactions: Reset State commands and Control Change
(0xB) for controller number 121 (Reset All Controllers) [RP015].
o Initiated parameter system transaction. A canonical parameter
system transaction whose (99, 98) or (101, 100) initial Control
Change command pair appears in the session history is considered
to be an initiated parameter system transaction. This definition
also holds for type 1 variants. For type 2 variants (dropped
MSB), a transaction whose initial LSB Control Change command
appears in the session history is an initiated transaction. For
type 3 variants (dropped LSB), a transaction is considered to be
initiated if at least one transaction command follows the initial
MSB (99 or 101) Control Change command in the session history.
The completion of a transaction does not nullify its "initiated"
status.
o Session history reference counts. Several recovery journal
chapters include a reference count field, which codes the total
number of commands of a type that appear in the session history.
Examples include the Reset and Tune Request command logs (Appendix
B.1, "System Chapter D") and the Active Sense command (Appendix
B.2, "System Chapter V"). Upon the detection of a loss event,
reference count fields let a receiver deduce if any instances of
the command have been lost, by comparing the journal reference
count with its own reference count. Thus, a reference count field
makes sense, even for command types in which knowing the NUMBER of
lost commands is irrelevant (as is true with all of the example
commands mentioned above).
The chapter definitions in Appendices A.2 to A.9 and B.1 to B.5
reflect the default recovery journal behavior. The ch_default,
ch_never, and ch_anchor parameters modify these definitions, as
described in Appendix C.2.3.
The chapter definitions specify if data MUST be present in the
journal. Senders MAY also include non-required data in the journal.
This optional data MUST comply with the normative chapter definition.
For example, if a chapter definition states that a field codes data
from the most recent active command in the session history, the
sender MUST NOT code inactive commands or older commands in the
field.
Finally, we note that a channel journal only encodes information
about MIDI commands appearing on the MIDI channel the journal
protects. All references to MIDI commands in Appendices A.2 to A.9
should be read as "MIDI commands appearing on this channel".
A.2. Chapter P: MIDI Program Change
A channel journal MUST contain Chapter P if an active Program Change
(0xC) command appears in the checkpoint history. Figure A.2.1 shows
the format for Chapter P.
0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|S| PROGRAM |B| BANK-MSB |X| BANK-LSB |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure A.2.1 -- Chapter P Format
The chapter has a fixed size of 24 bits. The PROGRAM field indicates
the data value of the most recent active Program Change command in
the session history. By default, the B, BANK-MSB, X, and BANK-LSB
fields MUST be set to 0. Below, we define exceptions to this default
condition.
If an active Control Change (0xB) command for controller number 0 (Bank Select MSB) appears before the Program Change command in the session history, the B bit MUST be set to 1, and the BANK-MSB field MUST code the data value of the Control Change command. If B is set to 1, the BANK-LSB field MUST code the data value of the most recent Control Change command for controller number 32 (Bank Select LSB) that preceded the Program Change command coded in the PROGRAM field and followed the Control Change command coded in the BANK-MSB field. If no such Control Change command exists, the BANK- LSB field MUST be set to 0. If B is set to 1 and if a Control Change command for controller number 121 (Reset All Controllers) appears in the MIDI stream between the Control Change command coded by the BANK-MSB field and the Program Change command coded by the PROGRAM field, the X bit MUST be set to 1. Note that [RP015] specifies that Reset All Controllers does not reset the values of controller numbers 0 (Bank Select MSB) and 32 (Bank Select LSB). Thus, the X bit does not affect how receivers will use the BANK-LSB and BANK-MSB values when recovering from a lost Program Change command. The X bit serves to aid recovery in MIDI applications where controller numbers 0 and 32 are used in a non- standard way.A.3. Chapter C: MIDI Control Change
Figure A.3.1 shows the format for Chapter C. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 8 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |S| LEN |S| NUMBER |A| VALUE/ALT |S| NUMBER | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |A| VALUE/ALT | .... | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure A.3.1 -- Chapter C Format The chapter consists of a 1-octet header followed by a variable- length list of 2-octet controller logs. The list MUST contain at least one controller log. The 7-bit LEN field codes the number of controller logs in the list, minus one. We define the semantics of the controller log fields in Appendix A.3.2. A channel journal MUST contain Chapter C if the rules defined in this appendix require that one or more controller logs appear in the list.
A.3.1. Log Inclusion Rules
A controller log encodes information about a particular Control Change command in the session history. In the default use of the payload format, list logs MUST encode information about the most recent active command in the session history for a controller number. Logs encoding earlier commands MUST NOT appear in the list. Also, as a rule, the list MUST contain a log for the most recent active command for a controller number that appears in the checkpoint history. Below, we define exceptions to this rule: o MIDI streams may transmit 14-bit controller values using paired Most Significant Byte (MSB, controller numbers 0-31, 99, 101) and Least Significant Byte (LSB, controller numbers 32-63, 98, 100) Control Change commands [MIDI]. If the most recent active Control Change command in the session history for a 14-bit controller pair uses the MSB number, Chapter C MAY omit the controller log for the most recent active Control Change command for the associated LSB number, as the command ordering makes this LSB value irrelevant. However, this exception MUST NOT be applied if the sender is not certain that the MIDI source uses 14-bit semantics for the controller number pair. Note that some MIDI sources ignore 14-bit controller semantics and use the LSB controller numbers as independent 7-bit controllers. o If active Control Change commands for controller numbers 0 (Bank Select MSB) or 32 (Bank Select LSB) appear in the checkpoint history and if the command instances are also coded in the BANK- MSB and BANK-LSB fields of the Chapter P (Appendix A.2), Chapter C MAY omit the controller logs for the commands. o Several controller number pairs are defined to be mutually exclusive. Controller numbers 124 (Omni Off) and 125 (Omni On) form a mutually exclusive pair, as do controller numbers 126 (Mono) and 127 (Poly). If active Control Change commands for one or both members of a mutually exclusive pair appear in the checkpoint history, a log for the controller number of the most recent command for the pair in the checkpoint history MUST appear in the controller list. However, the list MAY omit the controller log for the most recent active command for the other number in the pair.
If active Control Change commands for one or both members of a
mutually exclusive pair appear in the session history, and if a
log for the controller number of the most recent command for the
pair does not appear in the controller list, a log for the most
recent command for the other number of the pair MUST NOT appear in
the controller list.
o If an active Control Change command for controller number 121
(Reset All Controllers) appears in the session history, the
controller list MAY omit logs for Control Change commands that
precede the Reset All Controllers command in the session history,
under certain conditions.
Namely, a log MAY be omitted if the sender is certain that a
command stream follows the Reset All Controllers semantics defined
in [RP015] and if the log codes a controller number for which
[RP015] specifies a reset value.
For example, [RP015] specifies that controller number 1
(Modulation Wheel) is reset to the value 0, and thus a controller
log for Modulation Wheel MAY be omitted from the controller log
list. In contrast, [RP015] specifies that controller number 7
(Channel Volume) is not reset, and thus a controller log for
Channel Volume MUST NOT be omitted from the controller log list.
o Appendix A.3.4 defines exception rules for the MIDI Parameter
System controller numbers 6, 38, and 96-101.
A.3.2. Controller Log Format
Figure A.3.2 shows the controller log structure of Chapter C.
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|S| NUMBER |A| VALUE/ALT |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure A.3.2 -- Chapter C Controller Log
The 7-bit NUMBER field identifies the controller number of the coded
command. The 7-bit VALUE/ALT field codes recovery information for
the command. The A bit sets the format of the VALUE/ALT field.
A log encodes recovery information using one of the following tools:
the value tool, the toggle tool, or the count tool.
A log uses the value tool if the A bit is set to 0. The value tool codes the 7-bit data value of a command in the VALUE/ALT field. The value tool works best for controllers that code a continuous quantity, such as number 1 (Modulation Wheel). The A bit is set to 1 to code the toggle or count tool. These tools work best for controllers that code discrete actions. Figure A.3.3 shows the controller log for these tools. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |S| NUMBER |1|T| ALT | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure A.3.3 -- Controller Log for ALT Tools A log uses the toggle tool if the T bit is set to 0. A log uses the count tool if the T bit is set to 1. Both methods use the 6-bit ALT field as an unsigned integer. The toggle tool works best for controllers that act as on/off switches, such as 64 (Damper Pedal (Sustain)). These controllers code the "off" state with control values 0-63 and the "on" state with 64-127. For the toggle tool, the ALT field codes the total number of toggles (off->on and on->off) due to Control Change commands in the session history, up to and including a toggle caused by the command coded by the log. The toggle count includes toggles caused by Control Change commands for controller number 121 (Reset All Controllers). Toggle counting is performed modulo 64. The toggle count is reset at the start of a session and whenever a Reset State command (Appendix A.1) appears in the session history. When these reset events occur, the toggle count for a controller is set to 0 (for controllers whose default value is 0-63) or 1 (for controllers whose default value is 64-127). The Damper Pedal (Sustain) controller illustrates the benefits of the toggle tool over the value tool for switch controllers. As often used in piano applications, the "on" state of the controller lets notes resonate, while the "off" state immediately damps notes to silence. The loss of the "off" command in an "on->off->on" sequence results in ringing notes that should have been damped silent. The toggle tool lets receivers detect this lost "off" command, but the value tool does not.
The count tool is conceptually similar to the toggle tool. For the count tool, the ALT field codes the total number of Control Change commands in the session history, up to and including the command coded by the log. Command counting is performed modulo 64. The command count is set to 0 at the start of the session and is reset to 0 whenever a Reset State command (Appendix A.1) appears in the session history. Because the count tool ignores the data value, it is a good match for controllers whose controller value is ignored, such as number 123 (All Notes Off). More generally, the count tool may be used to code a (modulo 64) identification number for a command.A.3.3. Log List Coding Rules
In this section, we describe the organization of controller logs in the Chapter C log list. A log encodes information about a particular Control Change command in the session history. In most cases, a command SHOULD be coded by a single tool (and, thus, a single log). If a number is coded with a single tool and this tool is the count tool, recovery Control Change commands generated by a receiver SHOULD use the default control value for the controller. However, a command MAY be coded by several tool types (and, thus, several logs, each using a different tool). This technique may improve recovery performance for controllers with complex semantics, such as controller number 84 (Portamento Control) or controller number 121 (Reset All Controllers) when used with a non-zero data octet (with the semantics described in [DLS2]). If a command is encoded by multiple tools, the logs MUST be placed in the list in the following order: count tool log (if any), followed by value tool log (if any), followed by toggle tool log (if any). The Chapter C log list MUST obey the oldest-first ordering rule (defined in Appendix A.1). Note that this ordering preserves the information necessary for the recovery of 14-bit controller values without precluding the use of MSB and LSB controller pairs as independent 7-bit controllers. In the default use of the payload format, all logs that appear in the list for a controller number encode information about one Control Change command -- namely, the most recent active Control Change command in the session history for the number.
This coding scheme provides good recovery performance for the standard uses of Control Change commands defined in [MIDI]. However, not all MIDI applications restrict the use of Control Change commands to those defined in [MIDI]. For example, consider the common MIDI encoding of rotary encoders ("infinite" rotation knobs). The mixing console MIDI convention defined in [LCP] codes the position of rotary encoders as a series of Control Change commands. Each command encodes a relative change of knob position from the last update (expressed as a clockwise or counter-clockwise knob-turning angle). As the knob position is encoded incrementally over a series of Control Change commands, the best recovery performance is obtained if the log list encodes all Control Change commands for encoder controller numbers that appear in the checkpoint history, not only the most recent command. To support application areas that use Control Change commands in this way, Chapter C may be configured to encode information about several Control Change commands for a controller number. We use the term "enhanced" to describe this encoding method, which we describe below. In Appendix C.2.3, we show how to configure a stream to use enhanced Chapter C encoding for specific controller numbers. In Section 5 in the main text, we show how the H bits in the recovery journal header (Figure 8) and in the channel journal header (Figure 9) indicate the use of enhanced Chapter C encoding. Here, we define how to encode a Chapter C log list that uses the enhanced encoding method. Senders that use the enhanced encoding method for a controller number MUST obey the rules below. These rules let a receiver determine which logs in the list correspond to lost commands. Note that these rules override the exceptions listed in Appendix A.3.1. o If N commands for a controller number are encoded in the list, the commands MUST be the N most recent commands for the controller number in the session history. For example, for N = 2, the sender MUST encode the most recent command and the second most recent command, not the most recent command and the third most recent command. o If a controller number uses enhanced encoding, the encoding of the least recent command for the controller number in the log list MUST include a count tool log. In addition, if commands are
encoded for the controller number whose logs have S bits set to 0,
the encoding of the least recent command with S = 0 logs MUST
include a count tool log.
The count tool is OPTIONAL for the other commands for the
controller number encoded in the list, as a receiver is able to
efficiently deduce the count tool value for these commands for
both single-packet and multi-packet loss events.
o The use of the value and toggle tools MUST be identical for all
commands for a controller number encoded in the list. For
example, either a value tool log MUST appear for all commands for
the controller number coded in the list or, alternatively, value
tool logs for the controller number MUST NOT appear in the list.
Likewise, either a toggle tool log MUST appear for all commands
for the controller number coded in the list or, alternatively,
toggle tool logs for the controller number MUST NOT appear in the
list.
o If a command is encoded by multiple tools, the logs MUST be placed
in the list in the following order: count tool log (if any),
followed by value tool log (if any), followed by toggle tool log
(if any).
These rules permit a receiver recovering from a packet loss to use
the count tool log to match the commands encoded in the list with its
own history of the stream, as we describe below. Note that the text
below describes a non-normative algorithm; receivers are free to use
any algorithm to match its history with the log list.
In a typical implementation of the enhanced encoding method, a
receiver computes and stores count, value, and toggle tool data field
values for the most recent Control Change command it has received for
a controller number.
After a loss event, a receiver parses the Chapter C list and
processes list logs for a controller number that uses enhanced
encoding as follows.
The receiver compares the count tool ALT field for the least recent
command for the controller number in the list against its stored
count data for the controller number to determine if recovery is
necessary for the command coded in the list. The value and toggle
tool logs (if any) that directly follow the count tool log are
associated with this least recent command.
To check more recent commands for the controller, the receiver detects additional value and/or toggle tool logs for the controller number in the list and infers count tool data for the command coded by these logs. This inferred data is used to determine if recovery is necessary for the command coded by the value and/or toggle tool logs. In this way, a receiver is able to execute only lost commands, without executing a command twice. While recovering from a single packet loss, a receiver may skip through S = 1 logs in the list, as the first S = 0 log for an enhanced controller number is always a count tool log. Note that the requirements in Appendix C.2.2.2 for protective sender and receiver actions during session startup for multicast operation are of particular importance for enhanced encoding, as receivers need to initialize their count tool data structures with recovery journal data in order to match commands correctly after a loss event. Finally, we note in passing that in some applications of rotary encoders, a good user experience may be possible without the use of enhanced encoding. These applications are distinguished by visual feedback of encoding position that is driven by the post-recovery rotary encoding stream and relatively low packet loss. In these domains, recovery performance may be acceptable for rotary encoders if the log list encodes only the most recent command and if both count and value logs appear for the command.A.3.4. The Parameter System
Readers may wish to review the Appendix A.1 definitions of "parameter system", "parameter system transaction", and "initiated parameter system transaction" before reading this section. Parameter system transactions update a MIDI Registered Parameter Numbers (RPN) or Non-Registered Parameter Numbers (NRPN) value. A parameter system transaction is a sequence of Control Change commands that may use the following controllers numbers: o Data Entry MSB (6) o Data Entry LSB (38) o Data Increment (96) o Data Decrement (97) o Non-Registered Parameter Number (NRPN) LSB (98) o Non-Registered Parameter Number (NRPN) MSB (99) o Registered Parameter Numbers (RPN) LSB (100) o Registered Parameter Numbers (RPN) MSB (101)
Control Change commands that are a part of a parameter system transaction MUST NOT be coded in Chapter C controller logs. Instead, these commands are coded in Chapter M, the MIDI Parameter chapter defined in Appendix A.4. However, Control Change commands that use the listed controllers as general-purpose controllers (i.e., outside of a parameter system transaction) MUST NOT be coded in Chapter M. Instead, the controllers are coded in Chapter C controller logs. The controller logs follow the coding rules stated in Appendix A.3.2 and A.3.3. The rules for coding paired LSB and MSB controllers, as defined in Appendix A.3.1, apply to the pairs (6, 38), (99, 98), and (101, 100) when coded in Chapter C. If active Control Change commands for controller numbers 6, 38, or 96-101 appear in the checkpoint history, and these commands are used as general-purpose controllers, the most recent general-purpose command instance for these controller numbers MUST appear as entries in the Chapter C controller list. MIDI syntax permits a source to use controllers 6, 38, 96, and 97 as parameter-system controllers and general-purpose controllers in the same stream. An RTP MIDI sender MUST deduce the role of each Control Change command for these controller numbers by noting the placement of the command in the stream and MUST use this information to code the command in Chapter C or Chapter M, as appropriate. Specifically, active Control Change commands for controllers 6, 38, 96, and 97 act in a general-purpose way when o no active Control Change commands that set an RPN or NRPN parameter number appear in the session history, or o the most recent active Control Change commands in the session history that set an RPN or NRPN parameter number code the null parameter (MSB value 0x7F, LSB value 0x7F), or o a Control Change command for controller number 121 (Reset All Controllers) appears more recently in the session history than all active Control Change commands that set an RPN or NRPN parameter number (see [RP015] for details). Finally, we note that a MIDI source that follows the recommendations of [MIDI] exclusively uses numbers 98-101 as parameter system controllers. Alternatively, a MIDI source may exclusively use 98-101 as general-purpose controllers and lose the ability to perform parameter system transactions in a stream.
In the language of [MIDI], the general-purpose use of controllers 98-101 constitutes a non-standard controller assignment. As most real-world MIDI sources use the standard controller assignment for controller numbers 98-101, an RTP MIDI sender SHOULD assume these controllers act as parameter system controllers, unless it knows that a MIDI source uses controller numbers 98-101 in a general-purpose way.A.4. Chapter M: MIDI Parameter System
Readers may wish to review the Appendix A.1 definitions for "C-active commands", "parameter system", "parameter system transaction", and "initiated parameter system transaction" before reading this appendix. Chapter M protects parameter system transactions for Registered Parameter Numbers (RPN) and Non-Registered Parameter Numbers (NRPN) values. Figure A.4.1 shows the format for Chapter M. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |S|P|E|U|W|Z| LENGTH |Q| PENDING | Log list ... | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure A.4.1 -- Top-Level Chapter M Format Chapter M begins with a 2-octet header. If the P header bit is set to 1, a 1-octet field follows the header, coding the 7-bit PENDING value and its associated Q bit. The 10-bit LENGTH field codes the size of Chapter M and conforms to semantics described in Appendix A.1. Chapter M ends with a list of zero or more variable-length parameter logs. Appendix A.4.2 defines the bitfield format of a parameter log. Appendix A.4.1 defines the inclusion semantics of the log list. A channel journal MUST contain Chapter M if the rules defined in Appendix A.4.1 require that one or more parameter logs appear in the list. A channel journal also MUST contain Chapter M if the most recent C- active Control Change command involved in a parameter system transaction in the checkpoint history is
o an RPN MSB (101) or NRPN MSB (99) controller, or
o an RPN LSB (100) or NRPN LSB (98) controller that completes the
coding of the null parameter (MSB value 0x7F, LSB value 0x7F).
This rule provides loss protection for partially transmitted
parameter numbers and for the null parameter numbers.
If the most recent C-active Control Change command involved in a
parameter system transaction in the session history is for the RPN
MSB or NRPN MSB controller, the P header bit MUST be set to 1, and
the PENDING field (and its associated Q bit) MUST follow the Chapter
M header. Otherwise, the P header bit MUST be set to 0, and the
PENDING field and Q bit MUST NOT appear in Chapter M.
If PENDING codes an NRPN MSB controller, the Q bit MUST be set to 1.
If PENDING codes an RPN MSB controller, the Q bit MUST be set to 0.
The E header bit codes the current transaction state of the MIDI
stream. If E = 1, an initiated transaction is in progress. Below,
we define the rules for setting the E header bit:
o If no C-active parameter system transaction Control Change
commands appear in the session history, the E bit MUST be set to
0.
o If the P header bit is set to 1, the E bit MUST be set to 0.
o If the most recent C-active parameter system transaction Control
Change command in the session history is for the NRPN LSB or RPN
LSB controller number and if this command acts to complete the
coding of the null parameter (MSB value 0x7F, LSB value 0x7F), the
E bit MUST be set to 0.
o Otherwise, an initiated transaction is in progress, and the E bit
MUST be set to 1.
The U, W, and Z header bits code properties that are shared by all
parameter logs in the list. If these properties are set, parameter
logs may be coded with improved efficiency (we explain how in A.4.2).
By default, the U, W, and Z bits MUST be set to 0. If all parameter
logs in the list code RPN parameters, the U bit MAY be set to 1. If
all parameter logs in the list code NRPN parameters, the W bit MAY be
set to 1. If the parameter numbers of all RPN and NRPN logs in the
list lie in the range 0-127 (and thus have an MSB value of 0), the Z
bit MAY be set to 1.
Note that C-active semantics appear in the preceding paragraphs because [RP015] specifies that pending Parameter System transactions are closed by a Control Change command for controller number 121 (Reset All Controllers).A.4.1. Log Inclusion Rules
Parameter logs code recovery information for a specific RPN or NRPN parameter. A parameter log MUST appear in the list if an active Control Change command that forms a part of an initiated transaction for the parameter appears in the checkpoint history. An exception to this rule applies if the checkpoint history only contains transaction Control Change commands for controller numbers 98-101 that act to terminate the transaction. In this case, a log for the parameter MAY be omitted from the list. A log MAY appear in the list if an active Control Change command that forms a part of an initiated transaction for the parameter appears in the session history. Otherwise, a log for the parameter MUST NOT appear in the list. Multiple logs for the same RPN or NRPN parameter MUST NOT appear in the log list. The parameter log list MUST obey the oldest-first ordering rule (defined in Appendix A.1), with the phrase "parameter transaction" replacing the word "command" in the rule definition. Parameter logs associated with the RPN or NRPN null parameter (LSB = 0x7F, MSB = 0x7F) MUST NOT appear in the log list. Chapter M uses the E header bit (Figure A.4.1) and the log list ordering rules to code null parameter semantics. Note that "active" semantics (rather than "C-active" semantics) appear in the preceding paragraphs because [RP015] specifies that pending Parameter System transactions are not reset by a Control Change command for controller number 121 (Reset All Controllers). However, the rule that follows uses C-active semantics because it concerns the protection of the transaction system itself, and [RP015] specifies that Reset All Controllers acts to close a transaction in progress. In most cases, parameter logs for RPN and NRPN parameters that are assigned to the ch_never parameter (Appendix C.2.3) MAY be omitted from the list. An exception applies if
o the log codes the most recent initiated transaction in the session
history, and
o a C-active command that forms a part of the transaction appears in
the checkpoint history, and
o the E header bit for the top-level Chapter M header (Figure A.4.1)
is set to 1.
In this case, a log for the parameter MUST appear in the list. This
log informs receivers recovering from a loss that a transaction is in
progress so that the receiver is able to correctly interpret RPN or
NRPN Control Change commands that follow the loss event.
A.4.2. Log Coding Rules
Figure A.4.2 shows the parameter log structure of Chapter M.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 8 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|S| PNUM-LSB |Q| PNUM-MSB |J|K|L|M|N|T|V|R| Fields ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure A.4.2 -- Parameter Log Format
The log begins with a header, whose default size (as shown in Figure
A.4.2) is 3 octets. If the Q header bit is set to 0, the log encodes
an RPN parameter. If Q = 1, the log encodes an NRPN parameter. The
7-bit PNUM-MSB and PNUM-LSB fields code the parameter number and
reflect the Control Change command data values for controllers 99 and
98 (for NRPN parameters) or 101 and 100 (for RPN parameters).
The J, K, L, M, and N header bits form a Table of Contents (TOC) for
the log and signal the presence of fixed-sized fields that follow the
header. A header bit that is set to 1 codes the presence of a field
in the log. The ordering of fields in the log follows the ordering
of the header bits in the TOC. Appendices A.4.2.1 and A.4.2.2 define
the fields associated with each TOC header bit.
The T and V header bits code information about the parameter log but
are not part of the TOC. A set T or V bit does not signal the
presence of any parameter log field.
If the rules in Appendix A.4.1 state that a log for a given parameter
MUST appear in Chapter M, the log MUST code sufficient information to
protect the parameter from the loss of active parameter transaction
Control Change commands in the checkpoint history.
This rule does not apply if the parameter coded by the log is assigned to the ch_never parameter (Appendix C.2.3). In this case, senders MAY choose to set the J, K, L, M, and N TOC bits to 0, coding a parameter log with no fields. Note that logs to protect parameters that are assigned to ch_never are REQUIRED under certain conditions (see Appendix A.4.1). The purpose of the log is to inform receivers recovering from a loss that a transaction is in progress so that the receiver is able to correctly interpret RPN or NRPN Control Change commands that follow the loss event. Parameter logs provide two tools for parameter protection: the value tool and the count tool. Depending on the semantics of the parameter, senders may use either tool, both tools, or neither tool to protect a given parameter. The value tool codes information a receiver may use to determine the current value of an RPN or NRPN parameter. If a parameter log uses the value tool, the V header bit MUST be set to 1, and the semantics defined in Appendix A.4.2.1 for setting the J, K, L, and M TOC bits MUST be followed. If a parameter log does not use the value tool, the V bit MUST be set to 0, and the J, K, L, and M TOC bits MUST also be set to 0. The count tool codes the number of transactions for an RPN or NRPN parameter. If a parameter log uses the count tool, the T header bit MUST be set to 1, and the semantics defined in Appendix A.4.2.2 for setting the N TOC bit MUST be followed. If a parameter log does not use the count tool, the T bit and the N TOC bit MUST be set to 0. Note that V and T are set if the sender uses value (V) or count (T) tool for the log on an ongoing basis. Thus, V may be set even if J = K = L = M = 0, and T may be set even if N = 0. In many cases, all parameters coded in the log list are of one type (RPN parameters or NRPN parameters), and all parameter numbers lie in the range 0-127. As described in Appendix A.4, senders MAY signal this condition by setting the top-level Chapter M header bit Z to 1 (to code the restricted range) and by setting the U or W bit to 1 (to code the parameter type). If the top-level Chapter M header codes Z = 1 and either U = 1 or W = 1, all logs in the parameter log list MUST use a modified header format. This modification deletes bits 8-15 of the bitfield shown in Figure A.4.2 to yield a 2-octet header. The values of the deleted PNUM-MSB and Q fields may be inferred from the U, W, and Z bit values.
A.4.2.1. The Value Tool
The value tool uses several fields to track the value of an RPN or NRPN parameter. The J TOC bit codes the presence of the octet shown in Figure A.4.3 in the field list. 0 0 1 2 3 4 5 6 7 +-+-+-+-+-+-+-+-+ |X| ENTRY-MSB | +-+-+-+-+-+-+-+-+ Figure A.4.3 -- ENTRY-MSB Field The 7-bit ENTRY-MSB field codes the data value of the most recent active Control Change command for controller number 6 (Data Entry MSB) in the session history that appears in a transaction for the log parameter. The X bit MUST be set to 1 if the command coded by ENTRY-MSB precedes the most recent Control Change command for controller 121 (Reset All Controllers) in the session history. Otherwise, the X bit MUST be set to 0. A parameter log that uses the value tool MUST include the ENTRY-MSB field if an active Control Change command for controller number 6 appears in the checkpoint history. Note that [RP015] specifies that Control Change commands for controller 121 (Reset All Controllers) do not reset RPN and NRPN values, and thus the X bit would not play a recovery role for MIDI systems that comply with [RP015]. However, certain renderers (such as DLS 2 [DLS2]) specify that certain RPN values are reset for some uses of Reset All Controllers. The X bit (and other bitfield features of this nature in this appendix) plays a role in recovery for renderers of this type. The K TOC bit codes the presence of the octet shown in Figure A.4.4 in the field list.
0 0 1 2 3 4 5 6 7 +-+-+-+-+-+-+-+-+ |X| ENTRY-LSB | +-+-+-+-+-+-+-+-+ Figure A.4.4 -- ENTRY-LSB Field The 7-bit ENTRY-LSB field codes the data value of the most recent active Control Change command for controller number 38 (Data Entry LSB) in the session history that appears in a transaction for the log parameter. The X bit MUST be set to 1 if the command coded by ENTRY-LSB precedes the most recent Control Change command for controller 121 (Reset All Controllers) in the session history. Otherwise, the X bit MUST be set to 0. As a rule, a parameter log that uses the value tool MUST include the ENTRY-LSB field if an active Control Change command for controller number 38 appears in the checkpoint history. However, the ENTRY-LSB field MUST NOT appear in a parameter log if the Control Change command associated with the ENTRY-LSB precedes a Control Change command for controller number 6 (Data Entry MSB) that appears in a transaction for the log parameter in the session history. The L TOC bit codes the presence of the octets shown in Figure A.4.5 in the field list. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |G|X| A-BUTTON | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure A.4.5 -- A-BUTTON Field The 14-bit A-BUTTON field codes a count of the number of active Control Change commands for controller numbers 96 and 97 (Data Increment and Data Decrement) in the session history that appear in a transaction for the log parameter. The M TOC bit codes the presence of the octets shown in Figure A.4.6 in the field list.
0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |G|R| C-BUTTON | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure A.4.6 -- C-BUTTON Field The 14-bit C-BUTTON field has semantics identical to A-BUTTON, except that Data Increment and Data Decrement Control Change commands that precede the most recent Control Change command for controller 121 (Reset All Controllers) in the session history are not counted. For both A-BUTTON and C-BUTTON, Data Increment and Data Decrement Control Change commands are not counted if they precede Control Changes commands for controller numbers 6 (Data Entry MSB) or 38 (Data Entry LSB) that appear in a transaction for the log parameter in the session history. The A-BUTTON and C-BUTTON fields are interpreted as unsigned integers, and the G bit associated with the field codes the sign of the integer (G = 0 for positive or zero, G = 1 for negative). To compute and code the count value, initialize the count value to 0, add 1 for each qualifying Data Increment command, and subtract 1 for each qualifying Data Decrement command. After each addition or subtraction, limit the count magnitude to 16383. The G bit codes the sign of the count, and the A-BUTTON or C-BUTTON field codes the count magnitude. For the A-BUTTON field, if the most recent qualified Data Increment or Data Decrement command precedes the most recent Control Change command for controller 121 (Reset All Controllers) in the session history, the X bit associated with A-BUTTON field MUST be set to 1. Otherwise, the X bit MUST be set to 0. A parameter log that uses the value tool MUST include the A-BUTTON and C-BUTTON fields if an active Control Change command for controller numbers 96 or 97 appears in the checkpoint history. However, to improve coding efficiency, this rule has several exceptions: o If the log includes the A-BUTTON field, and if the X bit of the A- BUTTON field is set to 1, the C-BUTTON field (and its associated R and G bits) MAY be omitted from the log.
o If the log includes the A-BUTTON field, and if the A-BUTTON and C-
BUTTON fields (and their associated G bits) code identical values,
the C-BUTTON field (and its associated R and G bits) MAY be
omitted from the log.
A.4.2.2. The Count Tool
The count tool tracks the number of transactions for an RPN or NRPN
parameter. The N TOC bit codes the presence of the octet shown in
Figure A.4.7 in the field list.
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|X| COUNT |
+-+-+-+-+-+-+-+-+
Figure A.4.7 -- COUNT Field
The 7-bit COUNT codes the number of initiated transactions for the
log parameter that appear in the session history. Initiated
transactions are counted if they contain one or more active Control
Change commands, including commands for controllers 98-101 that
initiate the parameter transaction.
If the most recent counted transaction precedes the most recent
Control Change command for controller 121 (Reset All Controllers) in
the session history, the X bit associated with the COUNT field MUST
be set to 1. Otherwise, the X bit MUST be set to 0.
Transaction counting is performed modulo 128. The transaction count
is set to 0 at the start of a session and is reset to 0 whenever a
Reset State command (Appendix A.1) appears in the session history.
A parameter log that uses the count tool MUST include the COUNT field
if an active command that increments the transaction count (modulo
128) appears in the checkpoint history.
A.5. Chapter W: MIDI Pitch Wheel
A channel journal MUST contain Chapter W if a C-active MIDI Pitch
Wheel (0xE) command appears in the checkpoint history. Figure A.5.1
shows the format for Chapter W.
0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |S| FIRST |R| SECOND | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure A.5.1 -- Chapter W Format The chapter has a fixed size of 16 bits. The FIRST and SECOND fields are the 7-bit values of the first and second data octets of the most recent active Pitch Wheel command in the session history. Note that Chapter W encodes C-active commands and thus does not encode active commands that are not C-active (see the second-to-last paragraph of Appendix A.1 for an explanation of chapter inclusion text in this regard). Chapter W does not encode "active but not C-active" commands because [RP015] declares that Control Change commands for controller number 121 (Reset All Controllers) act to reset the Pitch Wheel value to 0. If Chapter W encoded "active but not C-active" commands, a repair operation following a Reset All Controllers command could incorrectly repair the stream with a stale Pitch Wheel value.
(page 75 continued on part 4)
