akai-utils/docs/akaiutil.md

# akaiutil — AKAI Sampler Filesystem Tool

**Version 4.6.7** (21-OCT-2022) — GPLv2 — by Klaus Michael Indlekofer

Interactive console-based file manager for AKAI **S900/S950/S1000/S1100/S3000/CD3000** sampler disk images, floppies, hard drives, and CD-ROMs.

## Usage

```
akaiutil [-h] [-r] [-F] [-C] [-l <lock-file>] [-o <start-offset>] [-s <pseudo-disk-size>]
         [-n <pseudo-disk-number>] [-c <cdrom-index> ...] [-p <physdrive-index> ...]
         [[-f] <floppy-drive>] ... [[-f] <disk-file>] ...
```

### Options

| Flag | Description |
|------|-------------|
| `-h` | Print help |
| `-r` | Read-only mode (must come first) |
| `-F` | Disable floppy filesystem detection |
| `-C` | Disable block cache |
| `-l <file>` | Lock file for exclusive access |
| `-o <offset>` | Byte offset where disk data starts (decimal or `0x` hex) |
| `-s <size>` | Pseudo-disk size in KB (for multi-disk images) |
| `-n <num>` | Max pseudo-disks per file descriptor (max 8) |
| `-c <n>` | (Windows) Open CD-ROM `\\.\cdromN` |
| `-p <n>` | (Windows) Open physical drive `\\.\physicaldriveN` |

On Linux, pass raw devices like `/dev/da1`, `/dev/disk2s0`.

### Examples

```bash
# Open a floppy image
akaiutil fff.img

# Open harddisk images
akaiutil hhh1.img hhh2.img

# Multi-harddisk image with explicit size
akaiutil -s 524280 mmm.img

# Linux raw device access
akaiutil /dev/da1 hhh.img

# Read-only CD-ROM (macOS)
akaiutil -r /dev/disk2s0
```

## Virtual Filesystem

```
/disk<N>/<partition-letter>/<volume-name>/<file-name>
```

Shorthand: `/N` = `/diskN`, `/floppyN` = `/diskN/A/<volume1>`. Use `_` for spaces in names. `.` and `..` work as usual.

## Interactive Commands

### Navigation & Info

| Command | Alias | Description |
|---------|-------|-------------|
| `help [<cmd>]` | `man` | List commands or show help for a command |
| `exit` / `quit` | `bye`, `q` | Exit |
| `restart` | — | Rescan disks |
| `restartkeep` | `restart.`, `sync` | Rescan, keep current directory |
| `df` | — | Show disk info (all disks + partitions) |
| `dinfo` | `pwd` | Show current directory info |
| `cd [<path>]` | — | Change directory |
| `cdi <index>` | — | Change to volume by index |
| `dir [<path>]` | `ls` | List directory |
| `dirrec` | `lsrec` | Recursive listing |
| `lcd <path>` | — | Change local (host) directory |
| `ldir` | `lls` | List local directory |
| `dircache` | `lscache` | Show block cache info |

### File Operations

| Command | Alias | Description |
|---------|-------|-------------|
| `del <path>` / `deli <idx>` | `rm` / `rmi` | Delete file |
| `ren <old> <new> [<idx>]` | `mv` | Rename/move file |
| `reni <old-idx> <new> [<idx>]` | `mvi` | Rename by index |
| `copy <src> <dst> [<idx>]` | `cp` | Copy file |
| `copyi <src-idx> <dst> [<idx>]` | `cpi` | Copy by index |
| `infoi <idx>` | — | Show file info |
| `infoall` | — | Show info for all files |

### Import / Export

| Command | Alias | Description |
|---------|-------|-------------|
| `get <path> [<begin> [<end>]]` | `export` | Export file to host |
| `geti <idx> [<begin> [<end>]]` | `exporti` | Export by index |
| `getall` | `exportall` | Export all files |
| `put [<vol>/]<name> [<idx>]` | `import` | Import file (use `*` for all) |
| `getdisk <file>` | `dget`, `dexport` | Export entire disk image |
| `putdisk <file>` | `dput`, `dimport` | Import disk image |
| `getpart [<path>] <file>` | `pget`, `pexport` | Export partition |
| `putpart <file> [<path>]` | `pput`, `pimport` | Import partition |
| `gettags <file>` | `tagsget` | Export partition tags |
| `puttags <file>` | `tagsput` | Import partition tags |

### WAV Conversion

| Command | Alias | Description |
|---------|-------|-------------|
| `sample2wav <path>` / `sample2wavi <idx>` | `s2wav` / `getwav` | Sample → WAV |
| `sample2wavall` | `s2wavall` | All samples → WAV |
| `wav2sample <file> [<idx>]` | `wav2s`, `putwav` | WAV → sample (auto-detect) |
| `wav2sample9` / `wav2sample9c` | `putwav9` / `putwav9c` | WAV → S900 (non-compressed / compressed) |
| `wav2sample1` | `putwav1` | WAV → S1000 |
| `wav2sample3` | `putwav3` | WAV → S3000 |

WAV input must be mono/stereo, 8/16/24/32-bit PCM.

### S900 Compression

| Command | Alias | Description |
|---------|-------|-------------|
| `sample900compr <path>` | `s9compr` | Compress S900 sample |
| `sample900comprall` | `s9comprall` | Compress all S900 samples |
| `sample900uncompr <path>` | `s9uncompr` | Uncompress S900 sample |
| `sample900uncomprall` | `s9uncomprall` | Uncompress all |

### Volume Management

| Command | Alias | Description |
|---------|-------|-------------|
| `mkvol [<path>]` | `mkdir` | Create volume (auto-detect type) |
| `mkvol9` / `mkvol1` / `mkvol3` / `mkvol3cd` | `mkdir9` etc. | Create S900/S1000/S3000/CD3000 volume |
| `mkvoli <idx> [<name> [<load-num>]]` | `mkdiri` | Create volume at specific index |
| `delvol <path>` / `delvoli <idx>` | `rmdir` | Delete volume |
| `wipevol <path>` / `wipevoli <idx>` | `rmall` | Wipe all files in volume |
| `renvol <old> <new>` | `mvdir` | Rename volume |
| `copyvol <src> <dst>` / `copyvoli <idx> <dst>` | `cpvol` | Copy volume |
| `copypart <src> <dst>` | `cppart` | Copy all volumes of a partition |
| `setosvervol <ver>` / `setlnum <num>` | — | Set volume OS version / load number |
| `fixramname <path>` / `fixramnameall` | — | Fix file name headers |

### Volume Parameters

| Command | Alias | Description |
|---------|-------|-------------|
| `lsparam` / `lsparami <idx>` | — | List parameters |
| `initparam` / `initparami <idx>` | — | Initialize parameters |
| `setparam <idx> <val>` / `setparami <vidx> <pidx> <val>` | — | Set parameter |
| `getparam <file>` / `putparam <file>` | `paramget` / `paramput` | Export/import parameters |

### Tag Management

| Command | Description |
|---------|-------------|
| `lstags` | List tags |
| `inittags` | Initialize all tags |
| `rentag <idx> <name>` | Rename a tag |
| `settagi <file-idx> <tag-idx>` / `settagall <tag-idx>` | Tag a file / all files |
| `clrtagi <file-idx> <tag-idx or all>` / `clrtagall <tag or all>` | Untag |
| `setfiltertag <idx>` / `clrfiltertag <idx or all>` | Filter by tag |

### Formatting / Filesystem Operations

| Command | Description |
|---------|-------------|
| `formatfloppyl9` / `l1` / `l3` | Format low-density floppy for S900/S1000/S3000 |
| `formatfloppyh9` / `h1` / `h3` | Format high-density floppy |
| `wipefloppy` | Create filesystem on floppy |
| `formatharddisk9 [<size>]` | Format HD for S900 (SH205, SUPRA20M, SUPRA30M, SUPRA60M, or size) |
| `formatharddisk1 [<part-size> [<total-size>]]` | Format HD for S1000 |
| `formatharddisk3 [<part-size> [<total-size>]]` | Format HD for S3000 |
| `formatharddisk3cd [<part-size> [<total-size>]]` | Format CD3000 CD-ROM |
| `wipepart` / `wipepart3cd` | Create filesystem in partition |
| `fixpart` / `fixharddisk` | Fix filesystem |
| `scanbadblkspart` / `scanbadblksdisk` | Scan for bad blocks |
| `markbadblkspart` / `markbadblksdisk` | Mark free bad blocks |
| `setcdinfo [<label>]` / `cdinfo` / `vcdinfo` | CD3000 CD-ROM info |

### FAT / Direct-to-Disk Takes

| Command | Alias | Description |
|---------|-------|-------------|
| `tinfoi <idx>` / `tinfoall` | — | DD take info |
| `tdeli <idx>` | `trmi` | Delete DD take |
| `treni <idx> <name>` | `tmvi` | Rename DD take |
| `tgeti <idx>` / `tgetall` | `texporti` | Export DD take (`.TK`) |
| `tput <file>` | `timport` | Import DD take (`*.TK` for all) |
| `take2wavi <idx>` / `take2wavall` | `t2wavi`, `getwavti` | DD take → WAV |
| `wav2take <file>` | `wav2t`, `putwavt` | WAV → DD take |

### Tar Archives

| Command | Alias | Description |
|---------|-------|-------------|
| `tarc <file>` | `gettar` | Create tar from current directory |
| `tarcwav <file>` | `gettarwav` | Tar-create with WAV conversion |
| `tarx <file>` | `puttar` | Extract tar (auto-detect type) |
| `tarx9` / `tarx1` / `tarx3` / `tarx3cd` | `puttar9` etc. | Extract as specific type |
| `tarxwav` | `puttarwav` | Extract with WAV → sample conversion |
| `tarxwav9` / `tarxwav9c` / `tarxwav1` / `tarxwav3` | — | Extract WAV as specific sampler type |

## Filesystem Types

| Type | Description | Block Size | Max Size / Blocks |
|------|-------------|------------|-------------------|
| FLL | Low-density floppy | 1 KB | 800 KB (800 blocks) |
| FLH | High-density floppy | 1 KB | 1600 KB (1600 blocks) |
| HD9 | S900/S950 harddisk | 8 KB | ~64 MB (8191 blocks) |
| HD | S1000/S3000 partition | 8 KB | 60 MB/partition, ~512 MB total |
| DD | S1100/S3000 Direct-to-Disk | 8 KB | ~512 MB |

## Build

```bash
make
```

Produces the `akaiutil` binary.