Nils Dagsson Moskopp // erlehmann http://dieweltistgarnichtso.net December 2011 The application/x-glitch Media Type for the glitch file format Status of This Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. This memo is licensed under the Creative Commons Share-Alike license, either Version 3, or, at your option, any later version. Abstract The glitch file format is a lightweight, text-based, language- independent program interchange format. It is used to specify programs to be executed on a stack machine that generates a bitstream. Outputs of such programs are commonly interpreted as audio waveforms. Doing this, many programs have been found to produce interesting musical results, referred to as “bytebeat” [BYTEBEAT]. 1. Introduction The glitch file format is a text format for the serialization of programs generating bitstreams. It is derived from the implementation of the iOS application Glitch Machine [GLITCHMACHINE]. Programs noted in the glitch file format (glitches) contain instructions for a stack machine and integer constants. Its design goals were for it to be minimal, portable and textual. The glitch file format was intended to be usable in microblogging applications. Those commonly limit textual messages to 140 characters to force messages to be terse and discourage intelligent discourse [HTML]. 1.1. Conventions Used in This Document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. The grammatical rules in this document are to be interpreted as described in [RFC4234]. 2. Glitch File Format Grammar A glitch consists of sequences of characters. In general, a glitch is written as follows: !<instructions> Title names consist of a sequence of zero or more characters, with an upper limit of 16 characters. The lower case letters "a"--"z", digits and the character underscore ("_") are allowed. Instructions consist of one or more lines, with an upper limit of 16 lines. Lines start with an exclamation mark followed by a sequence of one or more token, with an upper limit of 16 tokens. A tokens can be an opcode, a number or a period ("."). Opcodes tokens consist of single characters. The upper case letters "G"--"Z" and the lower case letters "a"--"z" are allowed. Numbers tokens consist of one to eight characters. The upper case letters "A"--"F" and the numbers "0"--"9" are allowed. Periods tokens are used as spacers whenever two numbers would otherwise be directly adjacent. 2.1 ABNF for the Glitch File Format alphalower = %x61-7A underscore = %x5F title = 0*16(alphalower / digit / underscore) opcode = %x47-5A / %x61-7A number = 1*8hexdig period = %x2E token = opcode / number / period newline = %0x21 line = newline 1*16token instructions = 1*16line glitch = title instructions [%x0A] 2.2. Advice for Implementors For interoperability with implementations using fixed-width glyphs, programs SHOULD NOT produce glitches with lines of more than 16 characters. Programs interpreting glitches SHOULD output a warning when encountering any title or line exceeding 16 characters. For robustness, programs SHOULD try to interpret such input, by truncating the title to 16 characters and splitting lines. If a program automatically truncates or splits lines, it SHOULD output a warning and SHOULD NOT let users save the changed content without further user intervention. Programs interpreting glitches MUST output a warning when encountering a sequence of more than eight characters from the set of the upper case letters "A"--"F" and the numbers "0"--"9" and SHOULD stop interpretation. Programs interpreting glitches MUST output a warning when encountering any character other than "A"--"Z", "a"--"z", "0"--"9", "_", ".", "!" or a single new line (LF) at the end of input and SHOULD stop interpretation. Warnings MUST NOT be output to the standard output. 3. Glitch Stack Machine 3.1. Stack Machine Interpreting programs written in the glitch file format is done using a virtual stack machine. The stack is a ring buffer with 256 cells that can hold an unsigned 32-bit integer and are initialized to hold a value of zero (0). In this context, setting a cell to a value means setting it to that value truncated to the last 32bits. A top-of-stack pointer (TOSP), holding an unsigned 8-bit integer, points to the current cell. Pushing a value to the stack means adding one (1) to the TOSP, then setting the current cell to that value. Popping from the stack means getting the current value, then subtracting one (1) from the TOSP. The stack machine has a global register referred to as “t”. […] 3.2. Tokenizer […] 3.3. Opcodes The following table details opcode names and their shorthands. For brevity, abbreviations are used for the top-of-stack pointer (TOSP), cell values (using stack indices within brackets “[” and “]”) and values retrieved or computed in previous numbered steps (V1, V2 …). Shorthand Name Description a T 1. Push the value of t to the stack. b PUT 1. Get [TOSP]. 2. Compute V1 modulo 256. 3. Compute V2 plus 1. 4. Get [TOSP + 1] 5. Set [TOSP - V3] to V4. 6. Pop the stack. c DROP 1. Pop from the stack. d MUL 1. Pop from the stack. 2. Pop from the stack. 3. Multiply V2 and V1. 4. Push V3 to the stack. e DIV 1. Pop from the stack. 2. Pop from the stack. 3. Divide V2 by V1, in case of a division by zero yielding zero. 4. Push V3 to the stack. f ADD 1. Pop from the stack. 2. Pop from the stack. 3. Add V2 and V1. 4. Push V3 to the stack. g SUB 1. Pop from the stack. 2. Pop from the stack. 3. From V2, subtract V1. 4. Push V3 to the stack. h MOD 1. Pop from the stack. 2. Pop from the stack. 3. Compute V2 modulo V1, in case of a division by zero yielding zero. 4. Push V3 to the stack. j LSHIFT 1. Pop from the stack. 2. Pop from the stack. 3. Compute V2 bit-shifted to the left by V1, shifting in zeros, in case of an overflow yielding zero. 4. Push V3 to the stack. k RSHIFT 1. Pop from the stack. 2. Pop from the stack. 3. Compute V2 bit-shifted to the right by V1, shifting in zeros, in case of an overflow yielding zero. 4. Push V3 to the stack. l AND 1. Pop from the stack. 2. Pop from the stack. 3. Compute a bitwise AND of V2 and V1. 4. Push V3 to the stack. m OR 1. Pop from the stack. 2. Pop from the stack. 3. Compute a bitwise OR of V2 and V1. 4. Push V3 to the stack. n XOR 1. Pop from the stack. 2. Pop from the stack. 3. Compute a bitwise XOR of V2 and V1. 4. Push V3 to the stack. o NOT 1. Pop from the stack. 2. Compute the bitwise NOT of V1. 3. Push V2 to the stack. p DUP 1. Pop from the stack. 2. Push V1 to the stack. 3. Push V1 to the stack. q PICK 1. Get [TOSP]. 2. Compute V1 plus 1. 3. Compute V2 modulo 256. 4. Get [TOSP - V3]. 5. Pop the stack. 6. Push V4 to the stack. r SWAP 1. Pop from the stack. 2. Pop from the stack. 3. Push V1 to the stack. 4. Push V2 to the stack. s LT 1. Pop from the stack. 2. Pop from the stack. 3. If V2 is smaller than V1, push 0xFFFFFFFF to the stack. 4. If V2 is greater than V1, push 0x00000000 to the stack. t GT 1. Pop from the stack. 2. Pop from the stack. 3. If V2 is greater than V1, push 0xFFFFFFFF to the stack. 4. If V2 is smaller than V1, push 0x00000000 to the stack. u EQ 1. Pop from the stack. 2. Pop from the stack. 3. If V2 and V1 are equal, push 0xFFFFFFFF to the stack. 4. If V2 and V1 are not equal, push 0x00000000 to the stack. Not listed lower case and upper case letters are reserved and MUST NOT be used for opcodes. Additional opcodes can be added to the specification as soon as two independent implementations with equal output exist and at least one other implementator pledges to also implement the specified behaviour. Programs interpreting glitches MAY optimize opcode behaviour, if the output does not change. 3.4. Execution and Output Programs interpreting glitches SHOULD execute all contained opcodes 8000 times per second. Programs MUST preserve the contents of the stack between successive interpretations of the same glitch. After each time a glitch is executed, a program MUST add one to the value of t. The last 8 bits of the value on the top of the stack at this time are then taken as a sample. Samples SHOULD be written to standard output, sound devices or files. Sample output MAY happen immediately or be buffered. If buffering is used, programs that output samples on standard output SHOULD buffer at most 256 samples at a time. The resulting output frequency of 31.25hz is adequate for visualisations. 4. IANA Considerations The MIME media type for the glitch file format is application/x-glitch. Type name: application Subtype name: x-glitch Required parameters: n/a Optional parameters: n/a Encoding considerations: A glitch MUST be represented using ASCII. 5. Security Considerations The glitch file format does not in itself pose a security threat. Due to lack of branching and looping instructions a conforming implementation can not enter an infinite loop. Implementors SHOULD ensure their implementations handle variable overflows and underflows securely. Users SHOULD take note that there is no general guarantee that an implementation contains no security holes. 6. Applications that use this media type The glitch file format has been used in libglitch [LIBGLITCH]. 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. 7.2. Informative References [BYTEBEAT] <http://canonical.org/~kragen/bytebeat/> [GLITCHMACHINE] <http://madgarden.net/apps/glitch-machine/> [HTML] <http://www.whatwg.org/specs/web-apps/current-work/ multipage/common-input-element-attributes.html #attr-input-maxlength> [LIBGLITCH] <https://github.com/erlehmann/libglitch>