1Home
2====
3 You can always find the latest version of libgig at:
4 http://www.linuxsampler.org/libgig/
5
6Content
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
62Requirements
63============
64
65 All systems
66 -----------
67
68 Since libgig 4.3.0 you need at least a C++11 compliant compiler.
69
70 POSIX systems (e.g. Linux, macOS):
71 ---------------------------------
72
73 You need at least to have libtool installed to be able to build the
74 library with "./configure && make".
75
76 Additionally you need to have either libaudiofile (>= 0.2.3) or
77 libsndfile (>= 1.0.2) installed which is mandatory to be able to compile
78 the 'gigextract' example application. But of course 'gigextract' is still
79 just an example application, so it would make sense to compile it only if
80 one of those libraries are available. That would remove that hard
81 dependency to those two libs. But that's not a priority for me now.
82 Note: for Windows systems only libsndfile is available.
83
84 If you want to regenerate all autotools build files (that is configure,
85 Makefile.in, etc.) then you need to have automake (>= 1.5) and autoconf
86 installed.
87
88 Windows:
89 --------
90
91 The precompiled versions of libgig (and its tools) should be compatible
92 with any Windows operating system of at least Win95 or younger. Notice
93 that all example / demo applications coming with libgig are pure console
94 applications, thus you won't see a GUI showing up! :)
95
96 If you want to compile libgig and its tools by yourself, please also
97 notice the requirements under "Compiling for Windows".
98
99 Other Operating Systems:
100 ------------------------
101
102 libgig was written to compile for any operating system, using standard C
103 library functions. However there are some OS dependent requirements:
104
105 * Since libgig 3.0.0 an OS dependent implementation for a tiny method called
106 RIFF::File::ResizeFile() is required. So you would either have to add
107 native OS API calls for that particular method, that is dependant to your
108 OS, or you have to add a portable implementation. No matter which way you
109 choose, please let us know! :)
110
111 * Since libgig 4.3.0 presence of some UUID generating function is required to
112 be provided by the underlying system. This was an optional feature in
113 previous versions of libgig for many years, its absence only meant that you
114 were unable to load gig files created/modified by libgig to be accepted by
115 Tascam's original GigaStudio studio software, did not mean any restriction
116 for being used with LinuxSampler though. This has changed in the meantime,
117 so this is now a hard build requirement, as you would potentially encounter
118 misbehaviours now even if you stay entirely in the Linux eco system if UUIDs
119 were missing in gig files.
120
121Compiling for Linux
122===================
123 You can either compile the sources and install the library directly on
124 your system or you can create Redhat or Debian packages.
125
126 a) Compiling and installing directly
127
128 Call './configure && make' on the console to compile the library, all
129 tools and demo applications, documentation and install them with
130 'make install'. The latter has to be called as root.
131
132 If you are compiling from CVS you have to call 'make -f Makefile.cvs'
133 to generate all autotools build files before calling
134 './configure && make'.
135
136 You can use 'make distclean' and probably 'make -f Makefile.cvs clean'
137 to clean up everything again. The latter will also delete all automatic
138 generated autools build files.
139
140 b) Creating Debian packages
141
142 Use 'dpkg-buildpackage -rfakeroot -b' to compile and create the Debian
143 packages. This will generate 3 Debian packages:
144
145 libgig: Contains the shared library files.
146 libgig-dev: Contains the header files and documentation for building
147 applications using libgig.
148 gigtools: Contains the tools and demo applications.
149
150 You can use 'fakeroot debian/rules clean' to clean up everything again.
151
152 c) Creating Redhat packages
153
154 You need to have the rpmbuild tool installed and properly configured to
155 create RPM packages. To create the RPM packages do the following:
156
157 * Get .spec file generated by ./configure and edit it as appropriate.
158
159 * Copy the source tarball to "/usr/src/<rpmdir>/SOURCES" directory,
160 where <rpmdir> is dependent to the system you are using. For SuSE
161 <rmpdir> will be "packages", for Mandrake <rpmdir> is "RPM" and for
162 Redhat / Fedora <rpmdir> always equals "redhat".
163
164 * Build the rpm(s) by invoking 'rpmbuild -bb <specfile>' from the
165 command line.
166
167 On success, the resulting rpm(s) can usually be found under the proper
168 "/usr/src/<rpmdir>/RPMS/<arch>" directory.
169
170Compiling for Windows using CMake
171=================================
172The easiest way is to compile is to use vcpkg (https://github.com/Microsoft/vcpkg)
173to install libsndfile (required) and cppunit (optional). In the vcpkg install dir
174type:
175.\vcpkg.exe install libsndfile cppunit [--triplet x64-windows]
176
177This should install the libraries in vcpkg, add the triplet option if you wish to
178get the 64bit libraries.
179
180In an empty directory type:
181cmake <libgig source dir> -DCMAKE_TOOLCHAIN_FILE=<vcpkg dir>\scripts\buildsystems\vcpkg.cmake
182[-G"Visual Studio 15 2017 Win64"]
183
184Use the -G option to select the visual studio version and whether to compile for
18564bits.
186
187This will create libgig.sln file which you can open in visual studio or you can use
188the following command line to compile:
189
190cmake --build . --config <Release|Debug|MinRelSize|RelWithDebInfo>
191
192Compiling for Windows using Dev-C++
193===================================
194
195 libgig and its tools can also be compiled on Windows using Bloodshed Dev-C++,
196 which is a free (GPL) C++ integrated development environment for Windows.
197 It is also possible to use MSYS from MinGW, which allows you to use
198 './configure && make' like the linux builds.
199
200 You can download Dev-C++ here:
201
202 http://www.bloodshed.net/devcpp.html
203
204 Make sure you install a version with Mingw integrated.
205
206 a) Compiling libgig.dll
207
208 Simply open the project file "win32/libgig.dev" either directly in Dev-C++
209 or by double clicking on the project file in the Windows explorer, then
210 click on "Compile" in the Dev-C++ menu and that's it! After compilation
211 finished, you can find the files "libgig.dll", "libgig.a" and
212 "liblibgig.def" in the "win32" directory.
213
214 b) Compiling the example tools "rifftree", "dlsdump" and "gigdump"
215
216 You need to have libgig.dll compiled as described in a). Then you can
217 compile the respective tool by simply opening the respective project
218 (.dev) file and clicking on "Compile" from the Dev-C++ menu. After
219 compilation you can find the respective .exe file in the "win32"
220 directory.
221
222 c) Compiling the example tool "gigextract"
223
224 You need to have libgig.dll compiled as described in a). Also you need
225 libsndfile (as DLL) which is used to create the .wav files. You can
226 download libsndfile already precompiled as DLL here:
227
228 http://www.mega-nerd.com/libsndfile/
229
230 Extract the .zip file i.e. to "C:\". The libsndfile .dll file should then
231 be i.e. under "C:\libsndfile-1_0_17". Beside the .dll file, make sure
232 libsndfile's .lib file exists in that directory as well. If the .lib file
233 does not exist yet, you have to create it with:
234
235 dlltool --input-def libsndfile-1.def --output-lib libsndfile-1.lib
236
237 Then you have to ensure the settings of gigextract's Dev-C++ project file
238 are pointing to the correct location of your local copy of libsndfile. For
239 that click in the Dev-C++ menu on "Project" -> "Project Options". Then
240 click on the tab "Parameter" and make sure the path to "libsndfile-1.lib"
241 in the "Linker" list view is correct. Then click on the tab "Directories"
242 and then on the tab "Include Directories" and make sure the path to
243 libsndfile points to the correct location there as well.
244
245 After that you should finally be able to compile "gigextract" by clicking
246 on "Compile" in the Dev-C++ menu. After compilation succeeded, you can
247 find the "gigextract.exe" file in the "win32" directory.
248
249Test Cases
250==========
251 The libgig sources come with a tiny console application which allows to
252 automatically test libgig's functions on your system. This test
253 application is not compiled by default, you have to compile it explicitly
254 with the following commands on the console (cppunit has to be installed):
255
256 cd src/testcases
257 make libgigtests
258
259 and then run the test application from the same directory with:
260
261 ./libgigtests
262
263License
264=======
265 libgig and its tools are released under the GNU General Public License (GPL).
266
267 libakai and its tools are released under the GNU Lesser General Public (LGPL).
268 Due to its different license model the Akai support part is built as separate
269 DLL (.so) file.
270
271API Documentation
272=================
273 If you have Doxygen installed you can generate the API documentation by
274 running 'make docs' in the sources' top level directory. The API
275 documentation will be generated in the 'doc' subdirectory.
276
277Patches
278=======
279 If you have bug fixes or improvements, your patches are always welcome!
280 Send them either directly to me or to the LinuxSampler developer's mailing
281 list <linuxsampler-devel@lists.sourceforge.net>.
282
283Bugs
284====
285 Please use http://bugs.linuxsampler.org to check and report possible bugs.
286 You might also try to run the "Test Cases" coming with libgig (see above),
287 especially in case you are running on an odd system.
288
289Trademarks
290==========
291 Tascam, Gigasampler, GigaStudio, KORG, Trinity, Triton, OASYS, M3, Kronos
292 and Akai are trademarks of their respective owners.
293
294Credits
295=======
296 The initial library (Gigasampler part) was based on the reverse engineering
297 effort of Paul Kellett and Ruben van Royen. We owe current support for the
298 Gigasampler v3/v4 format to Andreas Persson. Please also have a look at the
299 ChangeLog for all those who contributed.
300
301 Akai support files are a ported version of S�bastien M�trot's libakai. The
302 original libakai only supported Mac and Windows. This forked version of
303 libakai now also supports Linux and other POSIX compliant operating systems
304 as well and does not have a dependency to libngl as the original libakai had.
305
306 The SoundFont 2 file format C++ classes were written by Grigor Iliev.
307
308 Thanks to all of you for your great work!
309
310 Christian Schoenebeck <cuse@users.sourceforge.net>
311