Bus fixes: Reading of CPU MMIO registers does not update MDR
[lsnes.git] / manual.txt
blobafcf16f655f2a32839b6666dc5d59e9fc1f845da
1 1 Introduction
3 lsnes is SNES rerecording emulator based on bsnes core.
5 2 Dependencies
7 1. bsnes libsnes (for bsnes SNES core)
9   (a) v084-v087 (v084 or v085 for delayreset support)
11   (b) accuracy or compatiblity core with debugger enabled.
13   (c) Patched version (using included 7 patches)
15 2. gambatte (for gambatte core)
17   (a) SVN r320, r358 or r364
19   (b) Patched with included patches
21 3. Zlib
23 4. boost_iostreams
25 5. boost_filesystem
27 6. boost_thread (if native std::thread is not available)
29 7. libsdl (SDL only)
31 8. sdlmain (SDL only, part of SDL)
33 9. boost_conversion (this is header-only library)
35 10. libswscale (wxwidgets graphics only)
37 11. Portaudio (portaudio sound only)
39 12. libao (libao sound only)
41 13. Lua version 5.1.X or 5.2.X
43 14. G++ 4.6 or 4.7
45 15. libopus (optional, for commentary track tool)
47 3 Building
49 • Copy bsnes sources (the bsnes subdirectory) to subdirectory 
50   'bsnes' (for bsnes core).
52 • Copy gambatte sources to subdirectory 'gambatte' (for gambatte 
53   core).
55 • Patch the bsnes sources with included patches (directory 
56   'bsnes-patches/<version>', bsnes core)
58 • Patch the gambatte sources with included patches (directory 
59   'gambatte-patches/<version>', gambatte core)
61 • Edit options.build (or copy of that file)
63 • Run make (passing 'OPTIONS=<filename>' if using something else 
64   than options.build).
66 4 Command line options
68 4.1 Wxwidgets options
70 4.1.1 --rom=<file>
72 Load <file> as ROM.
74 4.1.2 <file>
76 Load <file> as ROM.
78 4.1.3 --load=<file>
80 Load <file> as movie or savestate file on startup.
82 4.1.4 --settings
84 Instead of starting the emulator, only display the settings.
86 4.1.5 --pluginmanager
88 Instead of starting the emulator, display the plugin manager 
89 (useful to disable some plugin that causes emulator to crash on 
90 startup)
92 4.1.6 --lua=<file>
94 Run this Lua file on startup
96 4.2 dump options (lsnes-dumpavi only)
98 4.2.1 --rom=<file>
100 Load <file> as ROM. Required.
102 4.2.2 <filename>
104 Load <filename> as movie or savestate file on startup. Required.
106 4.2.3 --dumper=<dumper>
108 Set the dumper to use (required). Use 'list' for listing of known 
109 dumpers.
111 4.2.4 --firmware-path=<path>
113 Set path to look for firmware.
115 4.2.5 --mode=<mode>
117 Set the mode to use (required for dumpers with multiple modes, 
118 forbidden otherwise). Use 'list' for known modes.
120 4.2.6 --prefix=<prefix>
122 Set dump prefix. Default is “avidump”.
124 4.2.7 --option=<name>=<value>
126 Set option <name> to value <value>.
128 4.2.8 --length=<length>
130 Set number of frames to dump. Mandatory, unless --overdump-length 
131 is specified.
133 4.2.9 --overdump-length=<length>
135 Set number of frames to dump after movie end. Mutually exclusive 
136 with --length.
138 4.2.10 --lua=<script>
140 Run specified lua script (lsnes-dumpavi does not have 
141 initialization files).
143 4.2.11 --load-library=<library>
145 Load the specified shared object / dynamic library / dynamic link 
146 library.
148 4.3 lsnes settings directory
150 The lsnes settings directory is (in order of decreasing 
151 perference):
153 • Windows: %APPDATA%\lsnes (if %APPDATA% exists)
155 • Unix: $XDG_CONFIG_HOME/lsnes (if $XDG_CONFIG_HOME exists)
157 • Unix: $HOME/.config/lsnes (if $HOME exists)
159 • All: . (fallback default).
161 If leading directories do not exist, attempt to create them is 
162 made.
164 5 Internal commands
166 • Commands beginning with '*' invoke the corresponding command 
167   without alias expansion.
169 • If command starts with '+' (after possible '*'), the command is 
170   executed as-is when button is pressed, and when button is 
171   released, it is executed with '+' replaced by '-'.
173 • Commands without '+' execute only on negative edge (release).
175 5.1 run-script <script>
177 Run <script> as if commands were entered on the command line.
179 5.2 Memory manipulation
181 • <address> can be one of:
183   – Decimal number
185   – Hexadecimal number (prefixed with 0x)
187   – <memarea>+<hexoffset> (no 0x prefix for offset).
189 <value> can be hexadecimal (prefixed with '0x'), unsigned or 
190 signed (prefixed with '-') decimal.
192 The available element <sizes> are:
194 • byte: 1 byte
196 • word: 2 bytes
198 • hword: 3 bytes
200 • dword: 4 bytes
202 • qword: 8 bytes
204 • float: 4 bytes (floating-point)
206 • double: 8 bytes (floating-point)
208 When reading RAM and ROM, multi-byte reads/writes are big-endian. 
209 When dealing with DSP memory, multi-byte reads/writes are 
210 native-endian (do not use operand sizes exceeding DSP bitness, 
211 except dword is OK for 24-bit memory).
213 5.2.1 read-<size> <address>
215 Read the value of byte in <address>.
217 5.2.2 read-s<size> <address>
219 Read the value of signed byte in <address>.
221 5.2.3 write-<size> <address> <value>
223 Write <value> to byte in address <address>.
225 5.3 Main commands
227 These commands are not available in lsnesrc, but are available 
228 after ROM has been loaded.
230 5.3.1 quit-emulator
232 Quits the emulator.
234 5.3.2 pause-emulator
236 Toggle paused/unpaused
238 5.3.3 +advance-frame 
240 Advance frame. If the button is still held after configurable 
241 timeout expires, game unpauses for the duration frame advance is 
242 held.
244 5.3.4 +advance-poll 
246 Advance subframe. If the button is still held after configurable 
247 timeout expires, game unpauses for the duration frame advance is 
248 held.
250 5.3.5 advance-skiplag 
252 Skip to first poll in frame after current.
254 5.3.6 reset 
256 Reset the SNES after this frame.
258 5.3.7 load <filename> 
260 Load savestate <filename> in current mode.
262 5.3.8 load-state <filename> 
264 Load savestate <filename> in readwrite mode.
266 5.3.9 load-readonly <filename> 
268 Load savestate <filename> in readonly mode.
270 5.3.10 load-preserve <filename> 
272 Load savestate <filename> in readonly mode, preserving current 
273 events.
275 5.3.11 load-movie <filename> 
277 Load savestate <filename>, ignoring save part in readonly mode.
279 5.3.12 save-state <filename> 
281 Save system state to <filename> as soon as possible.
283 5.3.13 save-movie <filename> 
285 Save movie to <filename>.
287 5.3.14 set-rwmode 
289 Set recording mode.
291 5.3.15 set-romode 
293 Set playback mode
295 5.3.16 toggle-rwmode 
297 Toggle between playback and recording modes.
299 5.3.17 test-1, test-2, test-3
301 Internal test commands. Don't use.
303 5.3.18 take-screenshot <filename> 
305 Save screenshot to <filename>.
307 5.3.19 +controller <class>-<#>-<button>
309 Press button <button> on controller <num> of class <class>.
311 • Class 'gamepad': A, B, X, Y, L, R, select, start, up, down, 
312   left, right, ext0, ext1, ext2, ext3
314 • Class 'mouse': L, R
316 • Class 'superscope': trigger, cursor, turbo, pause
318 • Class 'justifier': trigger, start
320 • Class 'gb': A, B, select, start, up, down, left, right
322 5.3.20 hold-controller <class>-<#>-<button>
324 Hold/unhold button <button> on controller <num> of class <class>.
326 5.3.21 type-controller <class>-<#>-<button>
328 Hold/unhold button <button> on controller <num> of class <class> 
329 for the next frame. See +controller for button names.
331 Cauntion: Does not work properly if outside frame advance.
333 5.3.22 +autofire-controller <class>-<#>-<button> [[<duty>] 
334   <cyclelen>]
336 Start autofire. If duty is not specified, defaults to 1. If 
337 <cyclelen> is not specified, defaults to 2.
339 5.3.23 -autofire-controller <class>-<#>-<button> [[<duty>] 
340   <cyclelen>]
342 End autofire.
344 5.3.24 autofire-controller <class>-<#>-<button> [[<duty>] 
345   <cyclelen>]
347 Toggle autofire. If autofire is turned on, specified cycle is 
348 used.
350 5.3.25 designate-position <class>-<#>-analog<n>
352 Designate position for analog pair. <n> is only there if there 
353 are multiple axis pairs.
355 5.3.26 repaint
357 Force a repaint.
359 5.3.27 toggle-pause-on-end
361 Toggle pause on end flag.
363 5.3.28 set-pause-on-end
365 Set pause on end flag.
367 5.3.29 clear-pause-on-end
369 Clear pause on end flag.
371 5.3.30 action <action> [<parameters>]
373 Run specified core action.
375 5.4 Save jukebox 
377 5.4.1 cycle-jukebox-backward
379 Cycle save jukebox backwards.
381 5.4.2 cycle-jukebox-forward
383 Cycle save jukebox forwards
385 5.4.3 set-jukebox-slot <slot>
387 Set current jukebox slot
389 5.4.4 load-jukebox
391 Do load from jukebox (current mode).
393 5.4.5 save-jukebox
395 Do state save to jukebox.
397 5.5 Slot branches
399 5.5.1 list-branches
401 List all branches
403 5.5.2 create-branch <pid> <name>
405 Create a new branch, with <pid> as parent and <name> as name.
407 5.5.3 rename-branch <id> <name>
409 Rename branch <id> to <name>.
411 5.5.4 reparent-branch <id> <pid>
413 Set parent of branch <id> to <pid>.
415 5.5.5 set-branch <id>
417 Set current branch to <id>.
419 5.5.6 delete-branch <id>
421 Delete branch <id>.
425 5.6 Lua 
427 5.6.1 evaluate-lua <luacode>
429 Run Lua code <luacode> using built-in Lua interpretter.
431 5.6.2 L <luacode>
433 Synonym for evaluate-lua.
435 5.6.3 run-lua <script>
437 Run specified lua file using built-in Lua interpretter.
439 5.6.4 reset-lua
441 Clear the Lua VM state and restore to factory defaults.
443 5.7 Sound 
445 5.7.1 enable-sound <on/off> 
447 Enable/Disable sound.
449 5.8 Misc.
451 5.8.1 load-rom <file>
453 Loads ROM (format autodetected) from <file>.
455 5.8.2 reload-rom
457 Reloads the main ROM image from.
459 5.8.3 +tangent
461 Tangent for recording voice for commentary track. While pressed, 
462 record a stream.
464 5.8.4 advance-subframe-timeout
466 Subframe advance timeout in milliseconds. Default is 100.
468 5.8.5 set-speed <speed>
470 Set the speed multiplier. <speed> may be positive number (1 is 
471 normal speed) or “turbo” for turbo.
473 6 Settings
475 6.1 Core settings
477 6.2 AVI dumper settings
479 6.2.1 avi-large
481 AVI dumper: Always dump at 512x448 or 512x478 regardless of what 
482 the console outputs.
484 6.2.2 avi-left-border
486 AVI dumper: Set the default left border thickness (unless lua 
487 overrides) for dumps. Range 0-8191. Default is 0.
489 6.2.3 avi-right-border
491 AVI dumper: Set the default right border thickness (unless lua 
492 overrides) for dumps. Range 0-8191. Default is 0.
494 6.2.4 avi-top-border
496 AVI dumper: Set the default top border thickness (unless lua 
497 overrides) for dumps. Range 0-8191. Default is 0.
499 6.2.5 avi-bottom-border
501 AVI dumper: Set the default bottom border thickness (unless lua 
502 overrides) for dumps. Range 0-8191. Default is 0.
504 6.2.6 avi-maxframes
506 AVI dumper: Maximum number of frames per dump segment (0 => 
507 unlimited). Range 0-999999999. Default is 0.
509 6.2.7 avi-compresison
511 AVI dumper: Compression level (0-18).
513 • Compression levels 10 and above are not compatible with stock 
514   CSCD codec.
516 • Recomended level is 7.
518 6.2.8 avi-soundrate
520 AVI dumper: Set method of determining the sound rate.
522 • 0: Pick nearest of 8, 11.025, 12, 16, 22.05, 24, 32, 44.1, 48, 
523   64, 88.2, 96, 128, 176.4 and 192 kHz.
525 • 1: Round down to nearest integer.
527 • 2: Round up to nearest ingeter.
529 • 3: Multiply by denominator.
531 • 4: High quality 44.1kHz (SRC needed).
533 • 5: High quality 48kHz (SRC needed).
535 6.3 JMD options
537 6.3.1 jmd-compression
539 JMD dumper: Compression level (0-9).
541 7 Movie editor
543 • The editor edits in-memory movie.
545 • Because past can't be edited and readwrite mode doesn't allow 
546   future, editing only works in read only mode.
548 • Keyboard triggers the normal hotkeys and bindings.
550 7.1 Left button actions
552 • Clicking on cell in future (indicated by lack of redish 
553   background) toggles it (if it is a button) or prompts for a 
554   value (if it is an axis)
556 • Dragging vertically toggles sequence of buttons or changes a 
557   sequence of axis values.
559 7.2 Right button actions
561 The right mouse button pops up a context-sensitive menu:
563 • Toggle <something>: Toggle this button
565 • Change <something>: Change this axis value
567 • Insert frame after: Insert a frame after this frame
569 • Append frame: Append a frame to movie
571 • Append frames: Append specified number of frames to movie
573 • Delete frame: Delete this frame
575 • Delete subframe: Delete this subframe
577 • Truncate movie: Delete this subframe and everything after it.
579 • Scroll to frame: Prompt for a frame and scroll the display to 
580   that frame.
582 • Scroll to current frame: Scroll the display to current position
584 • Run to frame: Prompts for frame and runs the emulation to that 
585   frame.
587 • Change number of lines visible: Change the height of the movie 
588   display (1 to 255).
590 • Lock scroll to playback: While playing back or rewinding 
591   movies, the display will follow if enabled.
593 8 Memory watch expression syntax
595 Memory watch expressions has the following syntax elements:
597 ${foo}     The value of memory watch foo.
599 0x1234     Hexadecimal number 1234
601 12345      Decimal number 12345
603 3.141      Decimal number 3.141
605 -a         Unary negation
607 ~a         Bitwise NOT (integers only)
609 a*b        Multiplication
611 a/b        Division/quotent
613 a%b        Remainder (integers only)
615 a+b        Sum or string concatenation
617 a-b        Difference
619 a<<b       Shift left (integers only)
621 a>>b       Shift right (integers only). Arithmetic for signed.
623 a<b        Less than
625 a<=b       Less or equal to
627 a==b       Equal to
629 a!=b       Not equal to
631 a>=b       Greater or equal to
633 a>b        Greater than
635 a&b        Bitwise AND (integers only)
637 a^b        Bitwise XOR (integers only)
639 a|b        Bitwise OR (integers only)
641 a&&b       Logical AND
643 a||b       Logical OR
645 π          Numeric constant pi.
647 i          Imaginary unit
649 if(x,y)    If x is true, y, else false.
651 if(x,y,z)  If x is true, y, else z.
653 select(x...)
655            First value in x... that is not false, or false if 
656 none.
658 unsigned(x)
660            Cast x to unsigned.
662 signed(x)
664            Cast x to signed.
666 float(x)
668            Cast x to float.
670 min(x...)  The smallest value among x... or false if empty.
672 max(x...)  The largest value among x... or false if empty.
674 sum(x...)  Sum/concatenation of x... or false if empty.
676 prod(x...) Product of x... or false if empty.
678 sqrt(x)    Square root of x.
680 log(x)     Natural log of x.
682 log(x,y)   Log of y to base x.
684 exp(x)     e^x.
686 exp(x,y)   x^y
688 sin(x)     Sine of x
690 cos(x)     Cosine of x
692 tan(x)     Tangent of x
694 asin(x)    Arcsine of x
696 acos(x)    Arccosine of x
698 atan(x)    Arctangent of x
700 atan(x,y)  Angle between vector (x,y) and x-axis.
702 sinh(x)    Hyperbolic sine of x
704 cosh(x)    Hyperbolic cosine of x
706 tanh(x)    Hyperbolic tangent of x
708 arsinh(x)  Hyperbolic arsine of x
710 arcosh(x)  Hyperbolic arcosine of x
712 artanh(x)  Hyperbolic artangent of x
714 torad(x)   Convert x degrees to radians.
716 todeg(x)   Convert x radians to degrees.
718 re(x)      Real part of complex number x.
720 im(x)      Imaginary part of complex number x.
722 conj(x)    Complex conjugate of x.
724 abs(x)     Absolute value of x.
726 arg(x)     Argument of x.
728 pyth(x...) sqrt(sum(x^2)). I.e. pythagorean distance.
730 e          Base of natural logarithm
732 pi         Pi
734 true       Constant true
736 false      Constant false
740 9 Modifier and key names:
742 9.1 wxWidgets platform
744 9.1.1 Modifier names:
746 Following modifier names are known:
748 • alt
750 • ctrl
752 • shift 
754 • meta
756 • cmd (Mac OS X only)
758 9.1.2 Key names:
760 Following key names are known:
762 • back, tab, return, escape, space, exclaim, quotedbl, hash, 
763   dollar, percent, ampersand, quote, leftparen, rightparen, 
764   asterisk, plus, comma, minus, period, slash, 0, 1, 2, 3, 4, 5, 
765   6, 7, 8, 9, colon, semicolon, less, equals, greater, question, 
766   at, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, 
767   u, v, w, x, y, z, leftbracket, backslash, rightbracket, caret, 
768   underscore, backquote, a, b, c, d, e, f, g, h, i, j, k, l, m, 
769   n, o, p, q, r, s, t, u, v, w, x, y, z, leftcurly, pipe, 
770   rightcurly, tilde, delete, start, lbutton, rbutton, cancel, 
771   mbutton, clear, shift, alt, control, menu, pause, capital, end, 
772   home, lefT, up, right, down, select, print, execute, snapshot, 
773   insert, help, numpad0, numpad1, numpad2, numpad3, numpad4, 
774   numpad5, numpad6, numpad7, numpad8, numpad9, multiply, add, 
775   separator, subtract, decimal, divide, f1, f2, f3, f4, f5, f6, 
776   f7, f8, f9, f10, f11, f12, f13, f14, f15, f16, f17, f18, f19, 
777   f20, f21, f22, f23, f24, numlock, scroll, pageup, pagedown, 
778   numpad_space, numpad_tab, numpad_enter, numpad_f1, numpad_f2, 
779   numpad_f3, numpad_f4, numpad_home, numpad_left, numpad_up, 
780   numpad_right, numpad_down, numpad_pageup, numpad_pagedown, 
781   numpad_end, numpad_begin, numpad_insert, numpad_delete, 
782   numpad_equal, numpad_multiply, numpad_add, numpad_separator, 
783   numpad_subtract, numpad_decimal, numpad_divide, windows_left, 
784   windows_right, windows_menu, command, special1, special2, 
785   special3, special4, special5, special6, special7, special8, 
786   special9, special10, special11, special12, special13, 
787   special14, special15, special16, special17, special18, 
788   special19, special20
790 10 Movie file format
792 Movie file is .zip archive in itself, normal ZIP archive tools 
793 work on it (note: If you recompress it, do not use compression 
794 methods other than store and deflate and especially do not use 
795 encryption of any kind).
797 10.1 Detecting clean start/SRAM/Savestate
799 • If file has member “savestate” it is savestate, otherwise:
801 • If file has members with names starting “moviesram.” it is 
802   movie starting from SRAM, otherwise:
804 • It is movie starting from clear state.
806 10.2 Member: gametype
808 Type of game ROM and region (as one line). Valid values are:
811 +--------------+---------------------+--------+
812 |    Value     |       System        | Region |
813 +--------------+---------------------+--------+
814 +--------------+---------------------+--------+
815 |  snes_pal    |     Super NES       |  PAL   |
816 +--------------+---------------------+--------+
817 |   sgb_pal    |   Super Game Boy    |  PAL   |
818 +--------------+---------------------+--------+
819 |  snes_ntsc   |     Super NES       |  NTSC  |
820 +--------------+---------------------+--------+
821 |  sgb_ntsc    |   Super Game Boy    |  NTSC  |
822 +--------------+---------------------+--------+
823 |     bsx      | BS-X (non-slotted)  |  NTSC  |
824 +--------------+---------------------+--------+
825 | bsxslotted   |   BS-X (slotted)    |  NTSC  |
826 +--------------+---------------------+--------+
827 | sufamiturbo  |    Sufami Turbo     |  NTSC  |
828 +--------------+---------------------+--------+
831 Frame rates are:
834 +---------+-----------------+
835 | Region  | Framerate (fps) |
836 +---------+-----------------+
837 +---------+-----------------+
838 |  PAL    |   322445/6448   |
839 +---------+-----------------+
840 |  NTSC   | 10738636/178683 |
841 +---------+-----------------+
844 10.3 Member: port1
846 Contains type of port #1 (as one line). Valid values are 'none', 
847 'gamepad', 'multitap' and 'mouse'. If not present, defaults to 
848 'gamepad'.
850 10.4 Member: port2
852 Contains type of port #2 (as one line). Valid values are 'none', 
853 'gamepad', 'multitap', 'mouse', 'superscope', 'justifier' and 
854 'justifiers'. If not present, defaults to 'none'.
856 10.5 Member: gamename
858 Contains name of the game (as one line).
860 10.6 Member: authors
862 Contains authors, one per line. Part before '|' is the full name, 
863 part after is the nickname.
865 10.7 Member: systemid
867 Always “lsnes-rr1” (one line). Used to reject other saves.
869 10.8 Member: controlsversion
871 Always “0” (one line). Used to identify what controls are there.
873 10.9 Member: “coreversion”
875 Contains bsnes core version number (as one line).
877 10.10 Member: projectid
879 Contains project ID (as one line). Used to identify if two movies 
880 are part of the same project.
882 10.11 Member: {rom,slota,slotb}{,xml}.sha256
884 Contains SHA-256 of said ROM or ROM mapping file (as one line). 
885 Absent if corresponding file is absent.
887 10.12 Member: moviesram.<name>
889 Raw binary startup SRAM of kind <name>. Only present in 
890 savestates and movies starting from SRAM.
892 10.13 Member: saveframe
894 Contains frame number (as one line) of frame movie was saved on. 
895 Only present in savestates.
897 10.14 Member: lagcounter
899 Current value of lag counter (as one line). Only present in 
900 savestates.
902 10.15 Member: pollcounters
904 Contains poll counters (currently 100 of them), one per line. 
905 Each line is raw poll count if DRDY is set for it. Otherwise it 
906 is negative poll count minus one. Only present in savestates.
908 10.16 Member: hostmemory
910 Raw binary dump of host memory. Only present in savestates.
912 10.17 Member: savestate
914 The raw binary savestate itself. Savestate detection uses this 
915 file, only present in savestates.
917 10.18 Member: screenshot
919 Screenshot of current frame. Only present in savestates. First 2 
920 bytes are big-endian width of image, rest are 24-bit RGB image 
921 data. Height of image is inferred from the width and size of 
922 data.
924 10.19 Member: sram.<name>
926 Raw binary SRAM of kind <name> at time of savestate. Only present 
927 in savestates.
929 10.20 Member: input
931 The actual input track, one line per subframe (blank lines are 
932 skipped).
934 • If the first byte of each line is '.', ' ', <tab> or '|', then 
935   the line is part of same frame as previous, otherwise it starts 
936   a new frame.
938 • First subframe must start a new frame.
940 Length of movie in frames is number of lines in input file that 
941 start a new frame.
943 10.21 Member: subtitles
945 Subtitle track. Optional.
947 • Each line is in form <firstframe> <numframes> <text>.
949 • Linefeed is encoded as \n, backslash is encoded as \\.
951 10.22 Member: rerecords
953 Contains textual base-10 rerecord count (as one line; emulator 
954 just writes this, it doesn't read it) + 1.
956 10.23 Member: rrdata
958 This member stores set of load IDs. There is one load ID per 
959 rerecord (plus one corresponding to start of project).
961 • This member constists of concatenation of records
963 • Each record is 2-36 bytes long and can represent 1-16,843,009 
964   consequtive IDs.
966 • IDs are interpretted as 256-bit big-endian integers with 
967   warparound.
969 • Initial predicted ID is all zeroes.
971 Format of each record is:
973 • 1 byte: Opcode byte. Bits 0-4 are prefix length (prefixlen), 
974   bits 5-6 are count length (countlen). Bit 7 is unused.
976 • 32-prefixlen bytes of ID.
978 • countlen bytes of big-endian count (count).
980 Records are processed as follows:
982 • To form the first ID encoded by record, take the first 
983   prefixlen bytes predicted ID and append the read ID value to 
984   it. The result is the first ID encoded.
986 • If countlen is 0, record encodes 1 ID.
988 • If countlen is 1, record encodes 2+count IDs.
990 • If countlen is 2, record encodes 258+count IDs.
992 • If countlen is 3, record encodes 65794+count IDs.
994 • The new predicted ID is the next ID after last one encoded by 
995   the record.
997 The number of rerecords + 1 is equal to the sum of number of IDs 
998 encoded by all records.
1000 10.24 Member: starttime.second
1002 Movie starting time, second part. Epoch is Unix epoch. Default is 
1003 1,000,000,000.
1005 10.25 Member: starttime.subsecond
1007 Movie starting time, subsecond part. Unit is CPU clocks. Default 
1008 is 0.
1010 10.26 Member: savetime.second
1012 Movie saving time, second part. Default is starttime.second. Only 
1013 present in savestates.
1015 10.27 Member: savetime.subsecond
1017 Movie saving time, subsecond part. Default is 
1018 starttime.subsecond. Only present in savestates.
1020 11 lsvs file format (commentary tracks)
1022 11.1 Clusters
1024 • Each cluster is 8kB (8192 bytes) in size.
1026 • Cluster n starts at offset 8192*n in file.
1028 • The following clusters are system special:
1030   – Cluster 0 and all clusters with number multiple of 2048 
1031     (cluster tables)
1033   – Cluster 1 (superblock)
1035 11.2 Cluster tables
1037 • The cluster table describing cluster n is stored in cluster n & 
1038   ~0x7FF (zero last 11 bits of n).
1040 • This cluster table consists of 2048 4-byte big-endian integers.
1042 • Each entry describes a cluster in 16MB supercluster, in order.
1044 • The valid values for entries are:
1046   – 0x00000000: Free cluster
1048   – 0x00000001: Last cluster in chain.
1050   – 0xFFFFFFFF: System cluster (cluster tables and superblock)
1052   – (anything else): Number of next cluster in chain. Must not be 
1053     multiple of 2048.
1055 • Due to limitations of the format, there can be at most 2097052 
1056   superclusters, giving maximum file size of 16TB.
1058 11.3 Stream table
1060 • The stream table chain always starts in cluster 2.
1062 • Otherwise, it follows normal chaining.
1064 • The stream table consists of 16-byte entries:
1066   – The first 8 bytes of entry give big-endian beginning position 
1067     of stream in units of 1/48000 s.
1069   – The next 4 bytes of entry give big-endian beginning cluster 
1070     for control data. 0 here marks the entry as not present.
1072   – The last 4 bytes of entry give big-endian beginning cluster 
1073     for codec data.
1075 • Stream table clusters are normal clusters, following normal 
1076   chaining.
1078 • The stream begnning position is not guarenteed unique. There 
1079   can be multiple streams with the same starting position in the 
1080   file.
1082 11.4 Stream control data
1084 • The stream control data consists of entries 4 bytes each:
1086   – The first 2 bytes of entry gives big-endian length of packet
1088   – The next byte of entry gives audio length of packet in units 
1089     of 1/400 s.
1091   – The last byte is control byte.
1093     ∗ 0 means this entry is not present and the control data 
1094       ends.
1096     ∗ 1 is valid control entry.
1098 • The stream control data can also end by running into end of the 
1099   readable chain.
1101   – This happens if there happens to be exact multiple of 2048 
1102     packets in stream and number of packets is nonzero.
1104 • These clusters follow normal chaining.
1106 11.5 Stream codec data
1108 • Stream codec data consists of raw Opus data packets packed back 
1109   to back with nothing in between.
1111 • Warning: Due to internal limitations, this data must reside in 
1112   the first 65536 superclusters (that is, the first 1TB of the 
1113   file).
1115 11.6 Superblock
1117 • The superblock is stored in cluster 1. 
1119 • The first 11 bytes are “sefs-magic”<NUL>.
1121 • The rest are unused.
1123 • This cluster 1 is marked as system special.
1125 12 Known ROM extensions
1127 • SNES cartridge ROMs: sfc, smc, swc, fig, ufo, sf2, gd3, gd7, 
1128   dx2, mgd, mgh.
1130 • DMG cartridge ROMs: dmg, gb.
1132 • GBC cartridge ROMs: cgb, gbc.
1134 13 Gamepack files
1136 • The first line must be: “[GAMEPACK FILE]”.
1138 • There is one needed line: “type <systype>”. This sets system 
1139   type to <systype>. The following system types are valid:
1141   – snes (SNES)
1143   – bsx (BS-X non-slotted)
1145   – bsxslotted (BS-X slotted)
1147   – sufamiturbo (Sufami Turbo)
1149   – sgb (Super Game Boy)
1151   – dmg (Game Boy)
1153   – gbc (Game Boy Color)
1155   – gbc_gba (Game Boy Color with GBA initial register values)
1157 • Optionally a region can be specified: “region <region>”. The 
1158   following values are valid:
1160   – autodetect (Autodetect region: snes and sgb only)
1162   – ntsc (NTSC: snes, bsx, bsxslotted, sufamiturbo, sgb)
1164   – pal (PAL: snes, sgb)
1166   – world (World: dmg, gbc, gbc_gba)
1168 • ROM images are loaded as: “rom <type> <file>”. The following 
1169   types are valid:
1171   – rom (Cartridge ROM in snes, dmg, gbc, gbc_gba. BIOS in bsx, 
1172     bsxslotted, sufamiturbo)
1174   – bsx (Cartridge ROM in bsx, bsxslotted)
1176   – slot-a (Cartridge ROM in sufamiturbo)
1178   – slot-b (Cartridge ROM in sufamiturbo)
1180 • ROM markup can be loaded as: “xml <type> <file>”. The types 
1181   valid are the same as for ROMs.
1183 • Patches can be loaded as “patch[<offset>] <type> <file>”. The 
1184   types are the same as for ROMs.
1186   – Offset is given in form [+-]<number>. Usually offset is 
1187     either +0 or -512.
1189   – Default offset is +0.
1191 13.1 Example:
1193 [GAMEPACK FILE]
1195 type snes
1197 rom rom speedygonzales.sfc
1199 patch-512 rom sonicthehedgehog.ips
1201 13.2 Example 2:
1203 [GAMEPACK FILE]
1205 type sgb
1207 rom rom supergameboy.sfc
1209 rom dmg megamanV.dmg
1211 14 Quick'n'dirty encode guide
1213 1. Start the emulator and load the ROM and movie file.
1215 2. Set large AVI option 'set-setting avi-large on'
1217 3. Enable dumping 'dump-avi tmpdump' 
1219 4. Unpause and let it run until you want to end dumping.
1221 5. Close the emulator (closing the window is the easiest way). Or 
1222   use 'end-avi'.
1224 6. For each tmpdump*.avi file created, on command prompt, do 
1225   'x264 --crf 10 -o tmpdump_<numbers>.mkv tmpdump_<numbers>.avi'.
1227 7. Do 'sox tmpdump.sox tmpdump.ogg rate -v 32000'
1229 8. Do 'mkvmerge -o tmpdump_video.mkv tmpdump_0000000.mkv + 
1230   tmpdump_0000001.mkv + tmpdump_0000002.mkv' (list every 
1231   tmpdump_<numbers>.mkv, with + in between).
1233 9. Do 'mkvmerge -o final.mkv tmpdump_video.mkv tmpdump.ogg'. Now 
1234   final.mkv contains quick'n'dirty encode.
1236 15 Axis configurations for some gamepad types:
1238 15.1 XBox360 controller:
1240 Axes 2 and 5 (joystick<n>axis2 and joystick<n>axis5) should be 
1241 set to pressure-+.
1243 set-axis joystick0axis2 pressure-+
1245 set-axis joystick0axis5 pressure-+
1247 • This is needed for SDL only. EVDEV sets those types correctly.
1249 15.2 PS3 “sixaxis” controller:
1251 Axes 8-19 should be disabled.
1253 set-axis joystick0axis8 disabled
1255 set-axis joystick0axis9 disabled
1257 set-axis joystick0axis10 disabled
1259 set-axis joystick0axis11 disabled
1261 set-axis joystick0axis12 disabled
1263 set-axis joystick0axis13 disabled
1265 set-axis joystick0axis14 disabled
1267 set-axis joystick0axis15 disabled
1269 set-axis joystick0axis16 disabled
1271 set-axis joystick0axis17 disabled
1273 set-axis joystick0axis18 disabled
1275 set-axis joystick0axis19 disabled
1277 16 Errata:
1279 16.1 Problems from BSNES core:
1281 • The whole pending save stuff.
1283 • It is slow (especially accuracy).
1285 • Firmwares can't be loaded from ZIP archives.
1287 16.2 Other problems:
1289 • Modifiers don't work with pseudo-keys.
1291 • Audio for last dumped frame is not itself dumped.
1293 • Audio in UI is pretty bad in quality if game doesn't run at 
1294   full speed.