miragextract FAQ (sort-of)
--------------------------

These are not really 'frequently asked', because nobody's asked me a
single question about miragextract yet (it's brand new). Maybe this
should be called the SAQ (Someday Asked Questions) or the NYAQ (Not Yet
Asked Questions).

Q1. How does miragextract work?
A1. Basically, miragextract is a command-line wrapper for libmirage,
plus 'glue' to connect it to libsndfile. These libraries do all the
real work.

Q2. Why did you write it?
A1. There are a lot of little tools made to convert various CD image
formats to something useful. Most of them just convert to ISO, meaning
they don't handle audio tracks. Each image format has its own tool, and
a lot of them are old and unmaintained so they don't keep up with changes
in the proprietary formats. The libmirage developers gave us a wonderful
library, but previously the only way to use it was to use cdemu, which
works great but requires root privileges, uses an out-of-tree kernel
module, and only works on Linux. I thought it'd be nice to have a simple
tool that's at leat potentially portable, so here it is.

Q3. What would I use miragextract for?
A3. Well, I use it for extracting ISO images and audio files from old game
CDs, for use with modern game engines (e.g. Raze or NBlood), or sometimes
just to listen to the audio tracks. You can use it for anything you want
(it's licensed WTFPL, so that means *anything*).

Q4. Why is there no '-f mp3' option?
A4. Because miragextract uses libsndfile to write the audio files,
and its developer has chosen not to include mp3 support. If you really
need mp3 (if ogg and/or flac just won't satisfy you), you can always
convert to wav and use any mp3 converter (lame, ffmpeg, etc). Someday I
may actually add lame support to miragextract, but don't hold your breath.

Q5. Why do my extracted audio tracks sound like white noise?
A5. Try the -s flag. If you're on a big-endian platform and you have this
issue, I'd like to hear from you (email address found in README).

Q6. This track01.iso I just extracted isn't an ISO, it's something
else. How come it's got .iso in the filename?
A6. Just rename it. miragextract doesn't have extensive file-type checking.
Currently, if it looks like an Apple disk image, it'll get named .dmg,
otherwise it's assumed to be a .iso.

Q7. I built a static binary of miragextract, but it fails (or still requires
shared libraries). Why?
A7. libmirage uses a plugin system for supporting the various formats it
knows about. This means it's basically impossible to compile libmirage
statically, so miragextract can't really be static either. It's probably
possible to make it work with an appropriate invocation of 'statifier'
but I haven't tried this yet.

Q8. Does it work on Windows, OSX, FreeBSD, ...?
A8. In principle, there's nothing Linux-specific in miragextract, libmirage,
or libsndfile. Porting to other OSes will require more knowledge of those OSes
(and more time) than I currently have available, but I'll accept patches.

Q9. Can I use it with real CDs?
A9. No. libmirage doesn't support reading real CDs. Use regular CD-ripping
software to get audio tracks, and 'dd' to extract an iso image.

Q10. I'm trying to use miragextract to extract an ISO and ...
A10. Let me stop you right there: you're using the wrong tool for the job
you're trying to do. libmirage will accept an ISO as input, but all it
can 'extract' from it is a copy of the ISO itself. You probably want to
mount your ISO to extract files from it.