/[svn]/libgig/trunk/README

Diff of /libgig/trunk/README

Parent Directory | Revision Log | View Patch Patch

-revision 312 by schoenebeck,
Fri Nov 26 19:24:18 2004 UTC
+revision 3985 by schoenebeck,
Wed Aug  4 11:40:57 2021 UTC
 Line 1
+ Home
+ ====
+   You can always find the latest version of libgig at:
+   http://www.linuxsampler.org/libgig/
  Content
  =======
-   libgig actually consists of three parts:
+   libgig actually consists of three major parts:
    - RIFF classes (RIFF.h, RIFF.cpp): Provides convenient methods to parse and
                                       access arbitrary RIFF files.
-Line 10 
 Content
+Line 15 
 Content
                                       data.
    - gig classes (gig.h, gig.cpp):    These are based on the DLS classes and
                                       provide the necessary extensions for
-                                      the Gigasampler file format.
+                                      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.
+     wav2gig:     Creates a new .gig file from a set of .wav files.
+     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
  ============
-   I simply used automake & co this time so you will need to have automake,
-   autoconf and libtool installed. I used the following versions:
-     automake  1.6.3
+   All systems
-     autoconf  2.57
+   -----------
-   If you want to compile the 'gigextract' application that comes with these
+   Since libgig 4.3.0 you need at least a C++11 compliant compiler.
-   sources then you will additionally need to have libaudiofile (>= 0.2.3)
-   or libsndfile (>= 1.0.2) installed. Note: for Windows systems only
-   libsndfile is available.
- Non-POSIX systems
+   POSIX systems (e.g. Linux, macOS):
- =================
+   ---------------------------------
-   If you don't have a POSIX system, you have to set 'POSIX' to '0' in RIFF.h.
-   Instead of using POSIX calls then standard C calls will be used for file
-   access. This applies e.g. to Windows systems.
- Compiling
+   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 there are some OS dependent requirements:
+   * Since libgig 3.0.0 an OS dependent implementation for a tiny method called
+     RIFF::File::ResizeFile() is required. 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! :)
+   * Since libgig 4.3.0 presence of some UUID generating function is required to
+     be provided by the underlying system. This was an optional feature in
+     previous versions of libgig for many years, its absence only meant that you
+     were unable to load gig files created/modified by libgig to be accepted by
+     Tascam's original GigaStudio studio software, did not mean any restriction
+     for being used with LinuxSampler though. This has changed in the meantime,
+     so this is now a hard build requirement, as you would potentially encounter
+     misbehaviours now even if you stay entirely in the Linux eco system if UUIDs
+     were missing in gig files.
+ 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
-   Use 'make -f Makefile.cvs && ./configure && make' to compile the library,
+   Call './configure && make' on the console to compile the library, all
-   all tools, demo applications, documentation and install them with
+   tools and demo applications, documentation and install them with
-   'make install'. You can use 'make distclean && make -f Makefile.cvs clean'
+   'make install'. The latter has to be called as root.
-   to clean up everything again.
+   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 'make -f Makefile.cvs && dpkg-buildpackage -rfakeroot -b' to compile
+   Use 'dpkg-buildpackage -rfakeroot -b' to compile and create the Debian
-   and create the Debian packages. This will generate 3 Debian packages:
+   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 && make -f Makefile.cvs clean'
+   You can use 'fakeroot debian/rules clean' to clean up everything again.
-   to clean up everything again.
    c) Creating Redhat packages
-Line 75 
 Compiling
+Line 168 
 Compiling
    On success, the resulting rpm(s) can usually be found under the proper
    "/usr/src/<rpmdir>/RPMS/<arch>" directory.
- Tools
+ 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
+bits.
+ 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.
-  Beside the actual library there are four applications:
+   b) Compiling the example tools "rifftree", "dlsdump" and "gigdump"
-      gigdump:     Demo app that prints out the content of a .gig file.
+   You need to have libgig.dll compiled as described in a). Then you can
-      gigextract:  Extracts samples from a .gig file.
+   compile the respective tool by simply opening the respective project
-      dlsdump:     Demo app that prints out the content of a DLS file.
+   (.dev) file and clicking on "Compile" from the Dev-C++ menu. After
-      rifftree:    Tool that prints out the RIFF tree of an arbitrary RIFF
+   compilation you can find the respective .exe file in the "win32"
-                   file.
+   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
-  If you have Doxygen installed you can generate the API documentation by
+   running 'make docs' in the sources' top level directory. The API
-  running 'make docs' in the sources' top level directory. The API
+   documentation will be generated in the 'doc' subdirectory.
-  documentation will be generated in the 'doc' subdirectory.
  Patches
  =======
-   If you find bugs or have improvements, your patches are always welcome!
+   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
  =======
-   This library is based on the reverse engineering work of Paul Kellett and
+   The initial library (Gigasampler part) was based on the reverse engineering
-   Ruben van Royen. Thanks for your great work!
+   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>

 Legend:



Removed from v.312
 


changed lines


 
Added in v.3985
 Legend:



Removed from v.312
 


changed lines


 
Added in v.3985
-Removed from v.312
+Added in v.3985

	ViewVC Help
Powered by ViewVC