-
Notifications
You must be signed in to change notification settings - Fork 13
/
FORMAT-draft-erlehmann
346 lines (247 loc) · 12.8 KB
/
FORMAT-draft-erlehmann
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
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>