Contents of /libgig/trunk/README

Home
====
  You can always find the latest version of libgig at:
  http://www.linuxsampler.org/libgig/

Content
=======
  libgig actually consists of three major parts:

  - RIFF classes (RIFF.h, RIFF.cpp): Provides convenient methods to parse and
                                     access arbitrary RIFF files.
  - DLS classes (DLS.h, DLS.cpp):    They're using the RIFF classes to parse
                                     DLS (Downloadable Sounds) Level 1 and 2
                                     files and provide abstract access to the
                                     data.
  - gig classes (gig.h, gig.cpp):    These are based on the DLS classes and
                                     provide the necessary extensions for
                                     the Gigasampler/GigaStudio file format.

  Despite its name, libgig also provides (since version 4.0.0) support for
  other sampler file formats as well:

  - SoundFont classes (SF.h, SF.cpp):  They provide support for the very popular
                                       SoundFont v1 and v2 format (.sf2).

  - KORG classes (Korg.h, Korg.cpp):   Provides support for sample based sounds
                                       used on many KORG synthesizer keyboards.

  - Akai classes (Akai.h):             Currently S1000, S01, S2000 and S3000
                                       series are supported.

  Additionally libgig contains the following separate API:

  - Serialization classes (Serialization.h, Serialization.cpp):
                                       Framework to serialize and deserialize
                                       the runtime state of native C++ objects
                                       (for saving and restoring their states
                                       as abstract data).

  Beside the actual library there are following example applications:

    gigdump:     Demo app that prints out the content of a .gig file.
    gigextract:  Extracts samples from a .gig file.
    gigmerge:    Merges several .gig files to one .gig file.
    gig2mono:    Converts .gig files from stereo to mono.
    gig2stereo:  Converts .gig files to true interleaved stereo sounds.
    dlsdump:     Demo app that prints out the content of a DLS file.
    korgdump:    Prints out the content of the various KORG file types.
    korg2gig:    Convert KORG sound file to Gigasampler/GigaStudio format.
    sf2dump:     Prints out the content of a .sf2 file.
    sf2extract:  Extracts audio samples from a .sf2 file.
    rifftree:    Tool that prints out the RIFF tree of an arbitrary RIFF
                 file.
    akaidump:    Dump an AKAI media i.e. from a CDROM drive as disk image file
                 to your hard disk drive.
    akaiextract: Extracts samples from an Akai disk image, either from a media
                 (i.e. CDROM or Zip drive) for from a AKAI disk image file.

  Since version 3.0.0 libgig also provides write support, that is for
  creating modifying .gig, DLS and RIFF files.

Requirements
============
  POSIX systems (e.g. Linux, macOS):
  ---------------------------------

  You need at least to have libtool installed to be able to build the
  library with "./configure && make".

  Additionally you need to have either libaudiofile (>= 0.2.3) or
  libsndfile (>= 1.0.2) installed which is mandatory to be able to compile
  the 'gigextract' example application. But of course 'gigextract' is still
  just an example application, so it would make sense to compile it only if
  one of those libraries are available. That would remove that hard
  dependency to those two libs. But that's not a priority for me now.
  Note: for Windows systems only libsndfile is available.

  If you want to regenerate all autotools build files (that is configure,
  Makefile.in, etc.) then you need to have automake (>= 1.5) and autoconf
  installed.

  Windows:
  --------

  The precompiled versions of libgig (and its tools) should be compatible
  with any Windows operating system of at least Win95 or younger. Notice
  that all example / demo applications coming with libgig are pure console
  applications, thus you won't see a GUI showing up! :)

  If you want to compile libgig and its tools by yourself, please also
  notice the requirements under "Compiling for Windows".

  Other Operating Systems:
  ------------------------

  libgig was written to compile for any operating system, using standard C
  library functions. However the latest versions of libgig lack a portable
  implementation of one tiny method called RIFF::File::ResizeFile(). So you
  would either have to add native OS API calls for that particular method,
  that is dependant to your OS, or you have to add a portable
  implementation. No matter which way you choose, please let us know! :)

Compiling for Linux
===================
  You can either compile the sources and install the library directly on
  your system or you can create Redhat or Debian packages.

  a) Compiling and installing directly

  Call './configure && make' on the console to compile the library, all
  tools and demo applications, documentation and install them with
  'make install'. The latter has to be called as root.

  If you are compiling from CVS you have to call 'make -f Makefile.cvs'
  to generate all autotools build files before calling
  './configure && make'.

  You can use 'make distclean' and probably 'make -f Makefile.cvs clean'
  to clean up everything again. The latter will also delete all automatic
  generated autools build files.

  b) Creating Debian packages

  Use 'dpkg-buildpackage -rfakeroot -b' to compile and create the Debian
  packages. This will generate 3 Debian packages:

    libgig:      Contains the shared library files.
    libgig-dev:  Contains the header files and documentation for building
                 applications using libgig.
    gigtools:    Contains the tools and demo applications.

  You can use 'fakeroot debian/rules clean' to clean up everything again.

  c) Creating Redhat packages

  You need to have the rpmbuild tool installed and properly configured to
  create RPM packages. To create the RPM packages do the following:

    * Get .spec file generated by ./configure and edit it as appropriate.

    * Copy the source tarball to "/usr/src/<rpmdir>/SOURCES" directory,
      where <rpmdir> is dependent to the system you are using. For SuSE
      <rmpdir> will be "packages", for Mandrake <rpmdir> is "RPM" and for
      Redhat / Fedora <rpmdir> always equals "redhat".

    * Build the rpm(s) by invoking 'rpmbuild -bb <specfile>' from the
      command line.

  On success, the resulting rpm(s) can usually be found under the proper
  "/usr/src/<rpmdir>/RPMS/<arch>" directory.

Compiling for Windows using CMake
=================================
The easiest way is to compile is to use vcpkg (https://github.com/Microsoft/vcpkg)
to install libsndfile (required) and cppunit (optional). In the vcpkg install dir
type:
.\vcpkg.exe install libsndfile cppunit [--triplet x64-windows]

This should install the libraries in vcpkg, add the triplet option if you wish to
get the 64bit libraries.

In an empty directory type:
cmake <libgig source dir> -DCMAKE_TOOLCHAIN_FILE=<vcpkg dir>\scripts\buildsystems\vcpkg.cmake
[-G"Visual Studio 15 2017 Win64"]

Use the -G option to select the visual studio version and whether to compile for
64bits.

This will create libgig.sln file which you can open in visual studio or you can use
the following command line to compile:

cmake --build . --config <Release|Debug|MinRelSize|RelWithDebInfo>

Compiling for Windows using Dev-C++
===================================

  libgig and its tools can also be compiled on Windows using Bloodshed Dev-C++,
  which is a free (GPL) C++ integrated development environment for Windows.
  It is also possible to use MSYS from MinGW, which allows you to use
  './configure && make' like the linux builds.

  You can download Dev-C++ here:

    http://www.bloodshed.net/devcpp.html

  Make sure you install a version with Mingw integrated.

  a) Compiling libgig.dll

  Simply open the project file "win32/libgig.dev" either directly in Dev-C++
  or by double clicking on the project file in the Windows explorer, then
  click on "Compile" in the Dev-C++ menu and that's it! After compilation
  finished, you can find the files "libgig.dll", "libgig.a" and
  "liblibgig.def" in the "win32" directory.

  b) Compiling the example tools "rifftree", "dlsdump" and "gigdump"

  You need to have libgig.dll compiled as described in a). Then you can
  compile the respective tool by simply opening the respective project
  (.dev) file and clicking on "Compile" from the Dev-C++ menu. After
  compilation you can find the respective .exe file in the "win32"
  directory.

  c) Compiling the example tool "gigextract"

  You need to have libgig.dll compiled as described in a). Also you need
  libsndfile (as DLL) which is used to create the .wav files. You can
  download libsndfile already precompiled as DLL here:

    http://www.mega-nerd.com/libsndfile/

  Extract the .zip file i.e. to "C:\". The libsndfile .dll file should then
  be i.e. under "C:\libsndfile-1_0_17". Beside the .dll file, make sure
  libsndfile's .lib file exists in that directory as well. If the .lib file
  does not exist yet, you have to create it with:

    dlltool --input-def libsndfile-1.def --output-lib libsndfile-1.lib

  Then you have to ensure the settings of gigextract's Dev-C++ project file
  are pointing to the correct location of your local copy of libsndfile. For
  that click in the Dev-C++ menu on "Project" -> "Project Options". Then
  click on the tab "Parameter" and make sure the path to "libsndfile-1.lib"
  in the "Linker" list view is correct. Then click on the tab "Directories"
  and then on the tab "Include Directories" and make sure the path to
  libsndfile points to the correct location there as well.

  After that you should finally be able to compile "gigextract" by clicking
  on "Compile" in the Dev-C++ menu. After compilation succeeded, you can
  find the "gigextract.exe" file in the "win32" directory.

Test Cases
==========
  The libgig sources come with a tiny console application which allows to
  automatically test libgig's functions on your system. This test
  application is not compiled by default, you have to compile it explicitly
  with the following commands on the console (cppunit has to be installed):

    cd src/testcases
    make libgigtests

  and then run the test application from the same directory with:

    ./libgigtests

License
=======
  libgig and its tools are released under the GNU General Public License (GPL).

  libakai and its tools are released under the GNU Lesser General Public (LGPL).
  Due to its different license model the Akai support part is built as separate
  DLL (.so) file.

API Documentation
=================
  If you have Doxygen installed you can generate the API documentation by
  running 'make docs' in the sources' top level directory. The API
  documentation will be generated in the 'doc' subdirectory.

Patches
=======
  If you have bug fixes or improvements, your patches are always welcome!
  Send them either directly to me or to the LinuxSampler developer's mailing
  list <linuxsampler-devel@lists.sourceforge.net>.

Bugs
====
  Please use http://bugs.linuxsampler.org to check and report possible bugs.
  You might also try to run the "Test Cases" coming with libgig (see above),
  especially in case you are running on an odd system.

Trademarks
==========
  Tascam, Gigasampler, GigaStudio, KORG, Trinity, Triton, OASYS, M3, Kronos
  and Akai are trademarks of their respective owners.

Credits
=======
  The initial library (Gigasampler part) was based on the reverse engineering
  effort of Paul Kellett and Ruben van Royen. We owe current support for the
  Gigasampler v3/v4 format to Andreas Persson. Please also have a look at the
  ChangeLog for all those who contributed.

  Akai support files are a ported version of S�bastien M�trot's libakai. The
  original libakai only supported Mac and Windows. This forked version of
  libakai now also supports Linux and other POSIX compliant operating systems
  as well and does not have a dependency to libngl as the original libakai had.

  The SoundFont 2 file format C++ classes were written by Grigor Iliev.

  Thanks to all of you for your great work!

 Christian Schoenebeck <cuse@users.sourceforge.net>
1	Home
2	====
3	You can always find the latest version of libgig at:
4	http://www.linuxsampler.org/libgig/
5
6	Content
7	=======
8	libgig actually consists of three major parts:
9
10	- RIFF classes (RIFF.h, RIFF.cpp): Provides convenient methods to parse and
11	access arbitrary RIFF files.
12	- DLS classes (DLS.h, DLS.cpp): They're using the RIFF classes to parse
13	DLS (Downloadable Sounds) Level 1 and 2
14	files and provide abstract access to the
15	data.
16	- gig classes (gig.h, gig.cpp): These are based on the DLS classes and
17	provide the necessary extensions for
18	the Gigasampler/GigaStudio file format.
19
20	Despite its name, libgig also provides (since version 4.0.0) support for
21	other sampler file formats as well:
22
23	- SoundFont classes (SF.h, SF.cpp): They provide support for the very popular
24	SoundFont v1 and v2 format (.sf2).
25
26	- KORG classes (Korg.h, Korg.cpp): Provides support for sample based sounds
27	used on many KORG synthesizer keyboards.
28
29	- Akai classes (Akai.h): Currently S1000, S01, S2000 and S3000
30	series are supported.
31
32	Additionally libgig contains the following separate API:
33
34	- Serialization classes (Serialization.h, Serialization.cpp):
35	Framework to serialize and deserialize
36	the runtime state of native C++ objects
37	(for saving and restoring their states
38	as abstract data).
39
40	Beside the actual library there are following example applications:
41
42	gigdump: Demo app that prints out the content of a .gig file.
43	gigextract: Extracts samples from a .gig file.
44	gigmerge: Merges several .gig files to one .gig file.
45	gig2mono: Converts .gig files from stereo to mono.
46	gig2stereo: Converts .gig files to true interleaved stereo sounds.
47	dlsdump: Demo app that prints out the content of a DLS file.
48	korgdump: Prints out the content of the various KORG file types.
49	korg2gig: Convert KORG sound file to Gigasampler/GigaStudio format.
50	sf2dump: Prints out the content of a .sf2 file.
51	sf2extract: Extracts audio samples from a .sf2 file.
52	rifftree: Tool that prints out the RIFF tree of an arbitrary RIFF
53	file.
54	akaidump: Dump an AKAI media i.e. from a CDROM drive as disk image file
55	to your hard disk drive.
56	akaiextract: Extracts samples from an Akai disk image, either from a media
57	(i.e. CDROM or Zip drive) for from a AKAI disk image file.
58
59	Since version 3.0.0 libgig also provides write support, that is for
60	creating modifying .gig, DLS and RIFF files.
61
62	Requirements
63	============
64	POSIX systems (e.g. Linux, macOS):
65	---------------------------------
66
67	You need at least to have libtool installed to be able to build the
68	library with "./configure && make".
69
70	Additionally you need to have either libaudiofile (>= 0.2.3) or
71	libsndfile (>= 1.0.2) installed which is mandatory to be able to compile
72	the 'gigextract' example application. But of course 'gigextract' is still
73	just an example application, so it would make sense to compile it only if
74	one of those libraries are available. That would remove that hard
75	dependency to those two libs. But that's not a priority for me now.
76	Note: for Windows systems only libsndfile is available.
77
78	If you want to regenerate all autotools build files (that is configure,
79	Makefile.in, etc.) then you need to have automake (>= 1.5) and autoconf
80	installed.
81
82	Windows:
83	--------
84
85	The precompiled versions of libgig (and its tools) should be compatible
86	with any Windows operating system of at least Win95 or younger. Notice
87	that all example / demo applications coming with libgig are pure console
88	applications, thus you won't see a GUI showing up! :)
89
90	If you want to compile libgig and its tools by yourself, please also
91	notice the requirements under "Compiling for Windows".
92
93	Other Operating Systems:
94	------------------------
95
96	libgig was written to compile for any operating system, using standard C
97	library functions. However the latest versions of libgig lack a portable
98	implementation of one tiny method called RIFF::File::ResizeFile(). So you
99	would either have to add native OS API calls for that particular method,
100	that is dependant to your OS, or you have to add a portable
101	implementation. No matter which way you choose, please let us know! :)
102
103	Compiling for Linux
104	===================
105	You can either compile the sources and install the library directly on
106	your system or you can create Redhat or Debian packages.
107
108	a) Compiling and installing directly
109
110	Call './configure && make' on the console to compile the library, all
111	tools and demo applications, documentation and install them with
112	'make install'. The latter has to be called as root.
113
114	If you are compiling from CVS you have to call 'make -f Makefile.cvs'
115	to generate all autotools build files before calling
116	'./configure && make'.
117
118	You can use 'make distclean' and probably 'make -f Makefile.cvs clean'
119	to clean up everything again. The latter will also delete all automatic
120	generated autools build files.
121
122	b) Creating Debian packages
123
124	Use 'dpkg-buildpackage -rfakeroot -b' to compile and create the Debian
125	packages. This will generate 3 Debian packages:
126
127	libgig: Contains the shared library files.
128	libgig-dev: Contains the header files and documentation for building
129	applications using libgig.
130	gigtools: Contains the tools and demo applications.
131
132	You can use 'fakeroot debian/rules clean' to clean up everything again.
133
134	c) Creating Redhat packages
135
136	You need to have the rpmbuild tool installed and properly configured to
137	create RPM packages. To create the RPM packages do the following:
138
139	* Get .spec file generated by ./configure and edit it as appropriate.
140
141	* Copy the source tarball to "/usr/src/<rpmdir>/SOURCES" directory,
142	where <rpmdir> is dependent to the system you are using. For SuSE
143	<rmpdir> will be "packages", for Mandrake <rpmdir> is "RPM" and for
144	Redhat / Fedora <rpmdir> always equals "redhat".
145
146	* Build the rpm(s) by invoking 'rpmbuild -bb <specfile>' from the
147	command line.
148
149	On success, the resulting rpm(s) can usually be found under the proper
150	"/usr/src/<rpmdir>/RPMS/<arch>" directory.
151
152	Compiling for Windows using CMake
153	=================================
154	The easiest way is to compile is to use vcpkg (https://github.com/Microsoft/vcpkg)
155	to install libsndfile (required) and cppunit (optional). In the vcpkg install dir
156	type:
157	.\vcpkg.exe install libsndfile cppunit [--triplet x64-windows]
158
159	This should install the libraries in vcpkg, add the triplet option if you wish to
160	get the 64bit libraries.
161
162	In an empty directory type:
163	cmake <libgig source dir> -DCMAKE_TOOLCHAIN_FILE=<vcpkg dir>\scripts\buildsystems\vcpkg.cmake
164	[-G"Visual Studio 15 2017 Win64"]
165
166	Use the -G option to select the visual studio version and whether to compile for
167	64bits.
168
169	This will create libgig.sln file which you can open in visual studio or you can use
170	the following command line to compile:
171
172	cmake --build . --config <Release\|Debug\|MinRelSize\|RelWithDebInfo>
173
174	Compiling for Windows using Dev-C++
175	===================================
176
177	libgig and its tools can also be compiled on Windows using Bloodshed Dev-C++,
178	which is a free (GPL) C++ integrated development environment for Windows.
179	It is also possible to use MSYS from MinGW, which allows you to use
180	'./configure && make' like the linux builds.
181
182	You can download Dev-C++ here:
183
184	http://www.bloodshed.net/devcpp.html
185
186	Make sure you install a version with Mingw integrated.
187
188	a) Compiling libgig.dll
189
190	Simply open the project file "win32/libgig.dev" either directly in Dev-C++
191	or by double clicking on the project file in the Windows explorer, then
192	click on "Compile" in the Dev-C++ menu and that's it! After compilation
193	finished, you can find the files "libgig.dll", "libgig.a" and
194	"liblibgig.def" in the "win32" directory.
195
196	b) Compiling the example tools "rifftree", "dlsdump" and "gigdump"
197
198	You need to have libgig.dll compiled as described in a). Then you can
199	compile the respective tool by simply opening the respective project
200	(.dev) file and clicking on "Compile" from the Dev-C++ menu. After
201	compilation you can find the respective .exe file in the "win32"
202	directory.
203
204	c) Compiling the example tool "gigextract"
205
206	You need to have libgig.dll compiled as described in a). Also you need
207	libsndfile (as DLL) which is used to create the .wav files. You can
208	download libsndfile already precompiled as DLL here:
209
210	http://www.mega-nerd.com/libsndfile/
211
212	Extract the .zip file i.e. to "C:\". The libsndfile .dll file should then
213	be i.e. under "C:\libsndfile-1_0_17". Beside the .dll file, make sure
214	libsndfile's .lib file exists in that directory as well. If the .lib file
215	does not exist yet, you have to create it with:
216
217	dlltool --input-def libsndfile-1.def --output-lib libsndfile-1.lib
218
219	Then you have to ensure the settings of gigextract's Dev-C++ project file
220	are pointing to the correct location of your local copy of libsndfile. For
221	that click in the Dev-C++ menu on "Project" -> "Project Options". Then
222	click on the tab "Parameter" and make sure the path to "libsndfile-1.lib"
223	in the "Linker" list view is correct. Then click on the tab "Directories"
224	and then on the tab "Include Directories" and make sure the path to
225	libsndfile points to the correct location there as well.
226
227	After that you should finally be able to compile "gigextract" by clicking
228	on "Compile" in the Dev-C++ menu. After compilation succeeded, you can
229	find the "gigextract.exe" file in the "win32" directory.
230
231	Test Cases
232	==========
233	The libgig sources come with a tiny console application which allows to
234	automatically test libgig's functions on your system. This test
235	application is not compiled by default, you have to compile it explicitly
236	with the following commands on the console (cppunit has to be installed):
237
238	cd src/testcases
239	make libgigtests
240
241	and then run the test application from the same directory with:
242
243	./libgigtests
244
245	License
246	=======
247	libgig and its tools are released under the GNU General Public License (GPL).
248
249	libakai and its tools are released under the GNU Lesser General Public (LGPL).
250	Due to its different license model the Akai support part is built as separate
251	DLL (.so) file.
252
253	API Documentation
254	=================
255	If you have Doxygen installed you can generate the API documentation by
256	running 'make docs' in the sources' top level directory. The API
257	documentation will be generated in the 'doc' subdirectory.
258
259	Patches
260	=======
261	If you have bug fixes or improvements, your patches are always welcome!
262	Send them either directly to me or to the LinuxSampler developer's mailing
263	list <linuxsampler-devel@lists.sourceforge.net>.
264
265	Bugs
266	====
267	Please use http://bugs.linuxsampler.org to check and report possible bugs.
268	You might also try to run the "Test Cases" coming with libgig (see above),
269	especially in case you are running on an odd system.
270
271	Trademarks
272	==========
273	Tascam, Gigasampler, GigaStudio, KORG, Trinity, Triton, OASYS, M3, Kronos
274	and Akai are trademarks of their respective owners.
275
276	Credits
277	=======
278	The initial library (Gigasampler part) was based on the reverse engineering
279	effort of Paul Kellett and Ruben van Royen. We owe current support for the
280	Gigasampler v3/v4 format to Andreas Persson. Please also have a look at the
281	ChangeLog for all those who contributed.
282
283	Akai support files are a ported version of S�bastien M�trot's libakai. The
284	original libakai only supported Mac and Windows. This forked version of
285	libakai now also supports Linux and other POSIX compliant operating systems
286	as well and does not have a dependency to libngl as the original libakai had.
287
288	The SoundFont 2 file format C++ classes were written by Grigor Iliev.
289
290	Thanks to all of you for your great work!
291
292	Christian Schoenebeck <cuse@users.sourceforge.net>