yaglitch/FORMAT-draft-erlehmann

                                       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:

   <title>!<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>