libMirage
3.2.1
~~~~~


Table of Contents:
~~~~~~~~~~~~~~~~~~

1. Introduction
2. Supported image formats
3. Requirements
4. Installation
5. Contact information


1. Introduction
~~~~~~~~~~~~~~~

This is libMirage library, a CD-ROM image access library, and part of the
userspace-cdemu suite, a free, GPL CD/DVD-ROM device emulator for linux. It is
written in C and based on GLib.

The aim of libMirage is to provide uniform access to the data stored in
different image formats, by creating a representation of disc stored in image
file, which is based on GObjects. There are various objects that represent
different parts of the disc; disc, session, track, sector, etc. In addition to
providing access to data provided by the image file, libMirage is also capable
of generating some of the data that might not be present in image file. For
instance, ISO image provides only user data from sector, without sync pattern,
header, ECC/EDC codes or subchannel. When this missing data is requested,
libMirage will transparently generate it.

libMirage has a plug-in based system, which allows a simple addition of new
image format parsers/writers or filter streams. It also supports runtime
debugging via debug traces; there are special debug context objects that can
be attached to other objects and used to control the amount of verbosity.


2. Supported image formats
~~~~~~~~~~~~~~~~~~~~~~~~~~

Currently supported image formats:
 - BlindWrite 5/6 (B5T, B6T) file format (readonly)
 - Roxio / WinOnCD (C2D) file format (readonly)
 - CloneCD (CCD, SUB, IMG) image format (readonly)
 - DiscJuggler (CDI) file format (readonly)
 - Easy CD Creator (CIF) file format (readonly)
 - CDRwin (CUE, BIN) image format (readonly)
 - Raw track loader (ISO, UDF etc.) image format (read-write)
 - Alcohol 120% (MDS) image format (readonly)
 - Daemon Tools (MDX) image format (readonly)
 - Nero Burning ROM (NRG) image format (readonly)
 - ReadCD (TOC, BIN) image format (readonly)
 - Cdrdao's (TOC, BIN) image format (read-write)
 - XCDRoast (TOC, BIN) image format (readonly)

Currently supported filter streams:
 - Apple Disk Image (DMG) container format (readonly)
 - Apple Disk Image (IMG, SMI) via MacBinary container format (readonly)
 - GZip (GZ) container format (readonly)
 - XZ (XZ) container format (readonly)
 - Compressed ISO (CSO) container format (readonly)
 - Compressed ISO (ISZ) container format (readonly)
 - Error Code Modeller (ECM) container format (readonly)
 - PowerISO (DAA) image format (readonly)
 - SNDFILE audio files (read-write)

2.1 Note about XZ-compressed images and XZ file filter:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The support for XZ-compressed images in libMirage is limited to streams
with reasonably-sized compressed blocks. This is to allow efficient
random access in the image, which requires a whole block to be
uncompressed in memory before data it contains can be accessed. A larger
block requires more time to be uncompressed and consumes more memory when
cached, whereas in random access, not all data it contains is necessarilly
needed. Therefore, for performance reasons, we enforce block size to
be 10 MB or less.

Unfortunately, xz from xz-utils by default creates an XZ file with a
single large block, which cannot be used with libMirage. If you wish to
use XZ-compressed images, use "--block-size" switch, for example,
"xz --block-size=10M ...". This requires 5.1.1alpha or later version of
xz-utils. Note that p7zip/7za cannot create single-file streams with
smaller blocks, so it cannot be used with libMirage.


3. Requirements:
~~~~~~~~~~~~~~~~

 - CMake >= 2.8.5
 - GLib >= 2.38
 - libsndfile >= 1.0.0
 - libsamplerate >= 0.1.0
 - zlib >= 1.2.0
 - libbz2 >= 1.0.0
 - liblzma >= 5.0.0

 - gtk-doc >= 1.4 (optional)
 - gobject-introspection >= 1.0 (optional)


4. Installation:
~~~~~~~~~~~~~~~~

Please read the INSTALL file.


5. Contact information:
~~~~~~~~~~~~~~~~~~~~~~~

CDEmu project's web page: http://cdemu.sourceforge.net
CDEmu project's mailing list: cdemu-devel@lists.sourceforge.net

Authors can be directly contacted via e-mail address listed in AUTHORS file.