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

Annotation of /libgig/trunk/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3878 - (hide annotations) (download)
Sun May 9 10:37:39 2021 UTC (2 years, 11 months ago) by schoenebeck
File size: 13277 byte(s)
* Preparations for new release (libgig 4.3.0).

1 schoenebeck 859 Home
2     ====
3     You can always find the latest version of libgig at:
4 schoenebeck 1406 http://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 650 dlsdump: Demo app that prints out the content of a DLS file.
48 schoenebeck 2543 korgdump: Prints out the content of the various KORG file types.
49     korg2gig: Convert KORG sound file to Gigasampler/GigaStudio format.
50 schoenebeck 2785 sf2dump: Prints out the content of a .sf2 file.
51     sf2extract: Extracts audio samples from a .sf2 file.
52 schoenebeck 650 rifftree: Tool that prints out the RIFF tree of an arbitrary RIFF
53     file.
54 schoenebeck 2572 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 schoenebeck 650
59 schoenebeck 859 Since version 3.0.0 libgig also provides write support, that is for
60     creating modifying .gig, DLS and RIFF files.
61    
62 schoenebeck 2 Requirements
63     ============
64 schoenebeck 3878
65     All systems
66     -----------
67    
68     Since libgig 4.3.0 you need at least a C++11 compliant compiler.
69    
70 schoenebeck 3370 POSIX systems (e.g. Linux, macOS):
71 schoenebeck 650 ---------------------------------
72 schoenebeck 2
73 schoenebeck 650 You need at least to have libtool installed to be able to build the
74     library with "./configure && make".
75 schoenebeck 2
76 schoenebeck 650 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 schoenebeck 859 installed.
87 schoenebeck 650
88 schoenebeck 1063 Windows:
89     --------
90 schoenebeck 859
91 schoenebeck 1063 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 schoenebeck 2
96 schoenebeck 1063 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 schoenebeck 3878 library functions. However there are some OS dependent requirements:
104 schoenebeck 1063
105 schoenebeck 3878 * 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    
121 schoenebeck 1063 Compiling for Linux
122     ===================
123 schoenebeck 186 You can either compile the sources and install the library directly on
124     your system or you can create Redhat or Debian packages.
125 schoenebeck 2
126 schoenebeck 186 a) Compiling and installing directly
127    
128 schoenebeck 650 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 schoenebeck 186
132 schoenebeck 650 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 schoenebeck 186 b) Creating Debian packages
141    
142 schoenebeck 650 Use 'dpkg-buildpackage -rfakeroot -b' to compile and create the Debian
143     packages. This will generate 3 Debian packages:
144 schoenebeck 186
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 schoenebeck 650 You can use 'fakeroot debian/rules clean' to clean up everything again.
151 schoenebeck 186
152     c) Creating Redhat packages
153    
154 schoenebeck 191 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 schoenebeck 186
157 schoenebeck 191 * 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    
170 schoenebeck 3476 Compiling for Windows using CMake
171     =================================
172     The easiest way is to compile is to use vcpkg (https://github.com/Microsoft/vcpkg)
173     to install libsndfile (required) and cppunit (optional). In the vcpkg install dir
174     type:
175     .\vcpkg.exe install libsndfile cppunit [--triplet x64-windows]
176 persson 1330
177 schoenebeck 3476 This should install the libraries in vcpkg, add the triplet option if you wish to
178     get the 64bit libraries.
179    
180     In an empty directory type:
181     cmake <libgig source dir> -DCMAKE_TOOLCHAIN_FILE=<vcpkg dir>\scripts\buildsystems\vcpkg.cmake
182     [-G"Visual Studio 15 2017 Win64"]
183    
184     Use the -G option to select the visual studio version and whether to compile for
185     64bits.
186    
187     This will create libgig.sln file which you can open in visual studio or you can use
188     the following command line to compile:
189    
190     cmake --build . --config <Release|Debug|MinRelSize|RelWithDebInfo>
191    
192     Compiling for Windows using Dev-C++
193     ===================================
194    
195     libgig and its tools can also be compiled on Windows using Bloodshed Dev-C++,
196 schoenebeck 1063 which is a free (GPL) C++ integrated development environment for Windows.
197 persson 1330 It is also possible to use MSYS from MinGW, which allows you to use
198     './configure && make' like the linux builds.
199 schoenebeck 1063
200 persson 1330 You can download Dev-C++ here:
201    
202 schoenebeck 1063 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    
249 schoenebeck 923 Test 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    
263 schoenebeck 859 License
264     =======
265 schoenebeck 2572 libgig and its tools are released under the GNU General Public License (GPL).
266 schoenebeck 859
267 schoenebeck 2572 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    
271 schoenebeck 186 API Documentation
272     =================
273 schoenebeck 859 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 schoenebeck 2
277 schoenebeck 11 Patches
278     =======
279 schoenebeck 923 If you have bug fixes or improvements, your patches are always welcome!
280 schoenebeck 11 Send them either directly to me or to the LinuxSampler developer's mailing
281     list <linuxsampler-devel@lists.sourceforge.net>.
282    
283 schoenebeck 923 Bugs
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    
289 schoenebeck 2543 Trademarks
290     ==========
291 schoenebeck 2572 Tascam, Gigasampler, GigaStudio, KORG, Trinity, Triton, OASYS, M3, Kronos
292     and Akai are trademarks of their respective owners.
293 schoenebeck 2543
294 schoenebeck 11 Credits
295     =======
296 schoenebeck 2543 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 schoenebeck 2572 Gigasampler v3/v4 format to Andreas Persson. Please also have a look at the
299     ChangeLog for all those who contributed.
300 schoenebeck 11
301 schoenebeck 2572 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 schoenebeck 2778 as well and does not have a dependency to libngl as the original libakai had.
305 schoenebeck 2572
306 schoenebeck 2785 The SoundFont 2 file format C++ classes were written by Grigor Iliev.
307    
308 schoenebeck 2572 Thanks to all of you for your great work!
309    
310 schoenebeck 2 Christian Schoenebeck <cuse@users.sourceforge.net>

  ViewVC Help
Powered by ViewVC