hootvopm/README.md

# hootvopm

This script was initially made to convert a [Hoot](http://snesmusic.org/hoot/v2/) memory dump into an .opm instrument pack, suitable for the VOPM VST plugin. It's an extremely rudimentary way of extracting FM instruments from games, but it works.

Over time, though, I've found myself slowly turning this into a general Yamaha 4op rip-o-tron.

## Usage

`./hootvopm.py [-b] -t format input_file`

Input file can also be `-` to read from stdin.

Output is dumped straight to stdout; redirect it to a file if you want to save it.

Pass -b to read straight binary data instead of comma-separated values.

### Currently-supported chip types and formats

| ID              | Description                                                    |
|-----------------|----------------------------------------------------------------|
| `raw` (Default) | Raw data in 32-byte groups; see table below                    |
| `opm`           | OPM register area                                              |
| `opn`           | OPN register area                                              |
| `opna`          | OPNA register area (similar to OPN but has 3 more instruments) |
| `solfeace`      | Format used in Sol-Feace for X68000 ("SOL.VCE")                |

#### Raw data format
| Offset | Value       |
|--------|-------------|
| 0x00   | DT/MUL*     |
| 0x04   | TL*         |
| 0x08   | KS/AR*      |
| 0x0C   | AMS-EN/D1R* |
| 0x10   | DT2/D2R*    |
| 0x14   | D1L/RR*     |
| 0x18   | FL/CON      |
| 0x19   | AMS/PMS     |

Rows marked with * are groups of 4 bytes, one per operator.

If you're curious, this is the format found in the PC-88VA version of Sorcerian, plus some padding bytes.

## Capturing memory in hoot

* Left- and right-clicking the "driver work" area flips between available memory pages. Scrolling the wheel in this area scrolls through the current page; you can also use Ctrl-(Up/Down/PgUp/PgDn) for this purpose.
* When you see the area you need to capture, use Ctrl-C to copy it to the clipboard. This copies the entire page to the clipboard in a human-readable format, with 16 comma-separated hex bytes per line (plus a comma at the end for whatever reason, but this is ignored).
* Paste this into a file, trimming it down to get the register area of the FM sound chip. Save it as whatever.

### Tips
* Most chips (read: all of the ones currently supported by this script) have a 256-byte register area, meaning you'll need to trim it down to 16 lines.
* From what I've seen, the chip's register area almost always resides on the first page, starting either at 0x0000 or 0x0100.
* This should be obvious, but for the formats that don't involve capturing the register area, you should pass `-b`.

## Known issues
* Since the script looks at a simple static memory dump, it has no way of capturing certain data, instead replacing it with placeholders. These include:
    * LFO data
    * Operator on/off state; all operators are considered to be in use (this *could* potentially be inferred, though)
    * Panning, though VOPM doesn't seem to use this