/[svn]/libgig/trunk/README
ViewVC logotype

Annotation of /libgig/trunk/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4075 - (hide annotations) (download)
Fri Jan 26 14:45:26 2024 UTC (3 months ago) by schoenebeck
File size: 13345 byte(s)
README: use https URL

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

  ViewVC Help
Powered by ViewVC