shithub: dumb

Download patch

ref: 657e36b7e60c9781ec4a8715e982955fd34e5305
parent: 6080f4c2a1b74d3536232d7a63533446b24f083b
parent: f1d59d806e85b33b71fca53424e64cf51fa49073
author: Christopher Snowhill <kode54@gmail.com>
date: Mon Sep 25 16:30:18 EDT 2017

Merge pull request #42 from Rondom/readme

Update README

--- /dev/null
+++ b/README.md
@@ -1,0 +1,93 @@
+# Dynamic Universal Music Bibliotheque (libdumb)
+
+     _______         ____    __         ___    ___
+    \    _  \       \    /  \  /       \   \  /   /       '   '  '
+     |  | \  \       |  |    ||         |   \/   |         .      .
+     |  |  |  |      |  |    ||         ||\  /|  |
+     |  |  |  |      |  |    ||         || \/ |  |         '  '  '
+     |  |  |  |      |  |    ||         ||    |  |         .      .
+     |  |_/  /        \  \__//          ||    |  |
+    /_______/ynamic    \____/niversal  /__\  /____\usic   /|  .  . ibliotheque
+                                                         /  \
+                                                        / .  \
+                                                       / / \  \
+                                                      | <  /   \_
+                                                      |  \/ /\   /
+                                                       \_  /  > /
+                                                         | \ / /
+                                                         |  ' /
+                                                          \__/
+
+
+
+## Introduction
+
+DUMB is a module audio renderer library. It reads module files and
+outputs audio that can be dumped to the actual audio playback library.
+
+## Features
+
+- Supports playback of the following module formats. The tracker software or
+  library the format is known for is given in parentheses. This does not mean
+  that DUMB does not support files created by other trackers provided that they
+  output files in one of those formats.
+
+   * IT (Impulse Tracker)
+   * XM (Fasttracker II)
+   * MOD (Ultimate SoundTracker, ProTracker)
+   * STM (Scream Tracker)
+   * S3M (Scream Tracker 3)
+   * 669 (Composer 669)
+   * AMF Asylum Music Format
+   * AMF Digital Sound and Music Interface Advanced Music Format
+   * DSM Digital Sound Interface Kit module format
+   * MTM (MultiTracker)
+   * OKT (Oktalyzer)
+   * PSM (Protracker Studio)
+     Both the older PSM16 and the newer PSM format is supported.
+   * PTM (PolyTracker)
+   * RIFF
+
+- Audio generated can be used in any way; DUMB does not necessarily send it
+  straight to a sound output system
+
+- Portable
+
+- Faithful to the original trackers, especially IT; if it plays a module
+  wrongly, it is considered a bug
+
+- Accurate support for low-pass resonant filters for IT files
+
+- Very accurate timing and pitching; completely deterministic playback
+
+- Click removal
+
+- Three resampling quality settings: aliasing, linear interpolation and cubic
+  interpolation
+
+- Number of samples playing at once can be limited to reduce processor usage,
+  but samples will come back in when other louder ones stop
+
+- Option to take longer loading but seek fast to any point before the music
+  first loops (seeking time increases beyond this point)
+
+- All notes will be present and correct even if a module's playback is started
+  in the middle
+
+- Optional Allegro4 integration support
+
+- Facility to embed music files in other files (e.g. Allegro datafiles)
+
+
+## Installation
+
+Currently you need to compile libdumb yourself. For more details, please see
+the file [COMPILING.md](COMPILING.md).
+
+## License
+
+See [LICENSE](LICENSE) for license details.
+
+## Contributing
+
+Bugs, feature requests and patches can be submitted at https://github.com/kode54/dumb/.
--- /dev/null
+++ b/examples/README.md
@@ -1,0 +1,19 @@
+# libdumb example programs
+
+Two simple example programs are provided.
+
+
+## dumbplay
+
+dumplay will play a module file from command-line. It requires SDL2 for audio
+output and argtable2 for argument parsing.
+
+
+## dumbout
+
+dumbout streams a module file to raw PCM. This can be used to pipe its output
+to an encoder such as oggenc (with appropriate command-line options). Or it can
+be written to a .pcm file which can be read by any respectable waveform editor.
+It is also convenient for timing DUMB. Compare the time it takes to render a
+module with the module's playing time! All options are set on the command line.
+The argtable2-library is required for argument parsing.
--- a/readme.txt
+++ /dev/null
@@ -1,541 +1,0 @@
-/*  _______         ____    __         ___    ___
- * \    _  \       \    /  \  /       \   \  /   /       '   '  '
- *  |  | \  \       |  |    ||         |   \/   |         .      .
- *  |  |  |  |      |  |    ||         ||\  /|  |
- *  |  |  |  |      |  |    ||         || \/ |  |         '  '  '
- *  |  |  |  |      |  |    ||         ||    |  |         .      .
- *  |  |_/  /        \  \__//          ||    |  |
- * /_______/ynamic    \____/niversal  /__\  /____\usic   /|  .  . ibliotheque
- *                                                      /  \
- *                                                     / .  \
- * readme.txt - General information on DUMB.          / / \  \
- *                                                   | <  /   \_
- *                                                   |  \/ /\   /
- *                                                    \_  /  > /
- *                                                      | \ / /
- *                                                      |  ' /
- *                                                       \__/
- */
-
-
-********************
-*** Introduction ***
-********************
-
-
-Thank you for downloading DUMB v0.9.3! You should have the following
-documentation:
-
-   readme.txt    - This file
-   licence.txt   - Conditions for the use of this software
-   release.txt   - Release notes and changes for this and past releases
-   docs/
-     howto.txt   - Step-by-step instructions on adding DUMB to your project
-     faq.txt     - Frequently asked questions and answers to them
-     dumb.txt    - DUMB library reference
-     deprec.txt  - Information about deprecated parts of the API
-     ptr.txt     - Quick introduction to pointers for those who need it
-     fnptr.txt   - Explanation of function pointers for those who need it
-     modplug.txt - Our official position regarding ModPlug Tracker
-
-This file will help you get DUMB set up. If you have not yet done so, please
-read licence.txt and release.txt before proceeding. After you've got DUMB set
-up, please refer to the files in the docs/ directory at your convenience. I
-recommend you start with howto.txt.
-
-
-****************
-*** Features ***
-****************
-
-
-Here is the statutory feature list:
-
-- Freeware
-
-- Supports playback of IT, XM, S3M and MOD files
-
-- Faithful to the original trackers, especially IT; if it plays your module
-  wrongly, please tell me so I can fix the bug! (But please don't complain
-  about differences between DUMB and ModPlug Tracker; see docs/modplug.txt)
-
-- Accurate support for low-pass resonant filters for IT files
-
-- Very accurate timing and pitching; completely deterministic playback
-
-- Click removal
-
-- Facility to embed music files in other files (e.g. Allegro datafiles)
-
-- Three resampling quality settings: aliasing, linear interpolation and cubic
-  interpolation
-
-- Number of samples playing at once can be limited to reduce processor usage,
-  but samples will come back in when other louder ones stop
-
-- All notes will be present and correct even if you start a piece of music in
-  the middle
-
-- Option to take longer loading but seek fast to any point before the music
-  first loops (seeking time increases beyond this point)
-
-- Audio generated can be used in any way; DUMB does not necessarily send it
-  straight to a sound output system
-
-- Can be used with Allegro, can be used without (if you'd like to help make
-  DUMB more approachable to people who aren't using Allegro, please contact
-  me)
-
-- Makefile provided for DJGPP, MinGW, Linux, BeOS and Mac OS X
-
-- Project files provided for MSVC 6
-
-- Autotools-based configure script available as a separate download for
-  masochists
-
-- Code should port anywhere that has a 32-bit C compiler; instructions on
-  compiling it manually are available further down
-
-
-*********************
-*** What you need ***
-*********************
-
-
-To use DUMB, you need a 32-bit C compiler (GCC and MSVC are fine). If you
-have Allegro, DUMB can integrate with its audio streams and datafiles, making
-your life easier. If you do not wish to use Allegro, you will have to do some
-work to get music playing back. The 'dumbplay' example program requires
-Allegro.
-
-   Allegro - http://alleg.sf.net/
-
-
-**********************************************
-*** How to set DUMB up with DJGPP or MinGW ***
-**********************************************
-
-
-You should have got the .zip version. If for some reason you got the .tar.gz
-version instead, you may have to convert make/config.bat to DOS text file
-format. WinZip does this automatically by default. Otherwise, loading it into
-MS EDIT and saving it again should do the trick (but do not do this to the
-Makefiles as it destroys tabs). You will have to do the same for any files
-you want to view in Windows Notepad. If you have problems, just go and
-download the .zip instead.
-
-Make sure you preserved the directory structure when you extracted DUMB from
-the archive. Most unzipping programs will do this by default, but pkunzip
-requires you to pass -d. If not, please delete DUMB and extract it again
-properly.
-
-If you are using Windows, open an MS-DOS Prompt or a Windows Command Line.
-Change to the directory into which you unzipped DUMB.
-
-If you are using MinGW (and you haven't renamed 'mingw32-make'), type:
-
-   mingw32-make
-
-Otherwise, type the following:
-
-   make
-
-DUMB will ask you whether you wish to compile for DJGPP or MinGW. Then it
-will ask you whether you want support for Allegro. (You have to have made and
-installed Allegro's optimised library for this to work.) Finally, it will
-compile optimised and debugging builds of DUMB, along with the example
-programs. When it has finished, run one of the following to install the
-libraries:
-
-   make install
-   mingw32-make install
-
-All done! If you ever need the configuration again (e.g. if you compiled for
-DJGPP before and you want to compile for MinGW now), run one of the
-following:
-
-   make config
-   mingw32-make config
-
-See the comments in the Makefile for other targets.
-
-Note: the Makefile will only work properly if you have COMSPEC or ComSpec set
-to point to command.com or cmd.exe. If you set it to point to a Unix-style
-shell, the Makefile won't work.
-
-Please let me know if you have any trouble.
-
-As an alternative, MSYS users may attempt to use the configure script,
-available in dumb-0.9.3-autotools.tar.gz. This has been found to work without
-Allegro, and is untested with Allegro. I should appreciate feedback from
-anyone else who tries this. I do not recommend its use, partly because it
-creates dynamically linked libraries and I don't know how to stop it from
-doing that (see the section on compiling DUMB manually), and partly because
-autotools are plain evil.
-
-Scroll down for information on the example programs. Refer to docs/howto.txt
-when you are ready to start programming with DUMB. If you use DUMB in a game,
-let me know - I might decide to place a link to your game on DUMB's website!
-
-
-******************************************************
-*** How to set DUMB up with Microsoft Visual C++ 6 ***
-******************************************************
-
-
-If you have a newer version of Microsoft Visual C++ or Visual Something that
-supports C++, please try these instructions and let me know if it works.
-
-You should have got the .zip version. If for some reason you got the .tar.gz
-version instead, you may have to convert some files to DOS text file format.
-WinZip does this automatically by default. Otherwise, loading such files into
-MS EDIT and saving them again should do the trick. You will have to do this
-for any files you want to view in Windows Notepad. If you have problems, just
-go and download the .zip instead.
-
-Make sure you preserved the directory structure when you extracted DUMB from
-the archive. Most unzipping programs will do this by default, but pkunzip
-requires you to pass -d. If not, please delete DUMB and extract it again
-properly.
-
-DUMB comes with a workspace Microsoft Visual C++ 6, containing projects for
-the DUMB core, the Allegro interface library and each of the examples. The
-first thing you might want to do is load the workspace up and have a look
-around. You will find it in the dumb\vc6 directory under the name dumb.dsw.
-Note that the aldumb and dumbplay projects require Allegro, so they won't
-work if you don't have Allegro. Nevertheless, dumbplay is the best-commented
-of the examples, so do have a look.
-
-When you are ready to add DUMB to your project, follow these instructions:
-
-1. Open your project in VC++.
-2. Select Project|Insert Project into Workspace...
-3. Navigate to the dumb\vc6\dumb directory and select dumb.dsp.
-   Alternatively, if you know that you are statically linking with a library
-   that uses the statically linked multithreaded runtime (/MT), you may wish
-   to select dumb_static.dsp in the dumb_static subdirectory instead.
-4. Select Build|Set Active Configuration..., and reselect one of your
-   project's configurations.
-5. Select Project|Dependencies... and ensure your project is dependent on
-   DUMB.
-6. Select Project|Settings..., Settings for: All Configurations, C/C++ tab,
-   Preprocessor category. Add the DUMB include directory to the Additional
-   Include Directories box.
-7. Ensure that for all the projects in the workspace (or more likely just all
-   the projects in a particular dependency chain) the run-time libraries are
-   the same. That's in Project|Settings, C/C++ tab, Code generation category,
-   Use run-time library dropdown. The settings for Release and Debug are
-   separate, so you'll have to change them one at a time. Exactly which run-
-   time library you use will depend on what you need; it doesn't appear that
-   DUMB has any particular requirements, so set it to whatever you're using
-   now. (It will have to be /MD, the multithreaded DLL library, if you are
-   statically linking with Allegro. If you are dynamically linking with
-   Allegro than it doesn't matter.)
-8. If you are using Allegro, do some or all of the above for the aldumb.dsp
-   project in the aldumb directory too.
-
-Good thing you only have to do all that once ... or twice ...
-
-If you have the Intel compiler installed, it will - well, should - be used to
-compile DUMB. The only setting I [Tom Seddon] added is /QxiM. This allows the
-compiler to use PPro and MMX instructions, and so when compiling with Intel
-the resultant EXE will require a Pentium II or greater. I don't think this is
-unreasonable. After all, it is 2003 :)
-
-[Note from Ben: the Intel compiler is evil! It makes AMD processors look bad!
-Patch it or boycott it or something!]
-
-If you don't have the Intel compiler, VC will compile DUMB as normal.
-
-This project file and these instructions were provided by Tom Seddon (I hope
-I got his name right; I had to guess it from his e-mail address!). Chad
-Austin has since changed the project files around, and I've just attempted to
-hack them to incorporate new source files. I've also tried to update the
-instructions using guesswork and some knowledge of Visual J++ (you heard me).
-The instructions and the project files are to this day untested by me. If you
-have problems, check the download page at http://dumb.sf.net/ to see if they
-are addressed; failing that, direct queries to me and I'll try to figure them
-out.
-
-If you have any comments at all on how the VC6 projects are laid out, or how
-the instructions could be improved, I should be really grateful to hear them.
-I am a perfectionist, after all. :)
-
-Scroll down for information on the example programs. When you are ready to
-start using DUMB, refer to docs/howto.txt. If you use DUMB in a game, let me
-know - I might decide to place a link to your game on DUMB's website!
-
-
-******************************************************
-*** How to set DUMB up on Linux, BeOS and Mac OS X ***
-******************************************************
-
-
-You should have got the .tar.gz version. If for some reason you got the .zip
-version instead, you may have to strip all characters with ASCII code 13 from
-some of the text files. If you have problems, just go and download the
-.tar.gz instead.
-
-You have two options. There is a Makefile which should cope with most
-systems. The first option is to use this default Makefile, and the procedure
-is explained below. The second option is to download
-dumb-0.9.3-autotools.tar.gz, extract it over the installation, run
-./configure and use the generated Makefile. Users who choose to do this are
-left to their own devices but advised to read the information at the end of
-this section. I strongly recommend the first option.
-
-If you are not using the configure script, the procedure is as follows.
-
-First, run the following command as a normal user:
-
-   make
-
-You will be asked whether you want Allegro support. Then, unless you are on
-BeOS, you will be asked where you'd like DUMB to install its headers,
-libraries and examples (which will go in the include/, lib/ and bin/
-subdirectories of the prefix you specify). BeOS has fixed locations for these
-files. You may use shell variables here, e.g. $HOME or ${HOME}, but ~ will
-not work. Once you have specified these pieces of information, the optimised
-and debugging builds of DUMB will be compiled, along with the examples. When
-it has finished, you can install them with:
-
-   make install
-
-You may need to be root for this to work. It depends on the prefix you chose.
-
-Note: the Makefile will only work if COMSPEC and ComSpec are both undefined.
-If either of these is defined, the Makefile will try to build for a Windows
-system, and will fail.
-
-Please let me know if you have any trouble.
-
-Scroll down for information on the example programs. Refer to docs/howto.txt
-when you are ready to start programming with DUMB. If you use DUMB in a game,
-let me know - I might decide to place a link to your game on DUMB's website!
-
-Important information for users of the configure script follows.
-
-The Makefile generated by the configure script creates dynamically linked
-libraries, and I don't know how to stop it from doing so. See the section
-below on building DUMB manually for why I recommend linking DUMB statically.
-However, if you choose to use the configure script, note the following.
-
-The default Makefile is a copy of Makefile.rdy (short for 'ready'), and it
-must exist with the name Makefile.rdy in order to work. The configure script
-will overwrite Makefile, so if you want the default Makefile back, just run:
-
-   cp Makefile.rdy Makefile
-
-Do not use a symlink, as that would result in Makefile.rdy getting
-overwritten next time the configure script is run!
-
-You can also access the usual build system by passing '-f Makefile.rdy' to
-Make.
-
-
-********************************************************
-*** How to build DUMB manually if nothing else works ***
-********************************************************
-
-
-Those porting to platforms without floating point support should be aware
-that DUMB does use floating point operations but not in the inner loops. They
-are used for volume and note pitch calculations, and they are used when
-initialising the filter algorithm for given cut-off and resonance values.
-Please let me know if this is a problem for you. If there is enough demand, I
-may be able to eliminate one or both of these cases.
-
-All of the library source code may be found in the src/ subdirectory. There
-are headers in the include/ subdirectory, and src/helpers/resample.c also
-#includes some .inc files in its own directory.
-
-There are four subdirectories under src/. For projects not using Allegro, you
-will need all the files in src/core/, src/helpers/ and src/it/. If you are
-using Allegro, you will want the src/allegro/ subdirectory too. For
-consistency with the other build systems, the contents of src/allegro/ should
-be compiled into a separate library.
-
-I recommend static-linking DUMB, since the version information is done via
-macros and the API has a tendency to change. If you static-link, then once
-your program is in binary form, you can be sure that changes to the installed
-version of DUMB won't cause it to malfuction. It is my fault that the API has
-been so unstable. Sorry!
-
-Compile each .c file separately. As mentioned above, you will need to specify
-two places to look for #include files: the include/ directory and the source
-file's own directory. You will also need to define the symbol
-DUMB_DECLARE_DEPRECATED on the command line.
-
-Do not compile the .inc files separately.
-
-You may need to edit dumb.h and add your own definition for LONG_LONG. It
-should be a 64-bit integer. If you do this, please see if you can add a check
-for your compiler so that it still works with other compilers.
-
-DUMB has two build modes. If you define the symbol DEBUGMODE, some checks for
-programmer error will be incorporated into the library. Otherwise it will be
-built without any such checks. (DUMB will however always thoroughly check the
-validity of files it is loading. If you ever find a module file that crashes
-DUMB, please let me know!)
-
-I recommend building two versions of the library, one with DEBUGMODE defined
-and debugging information included, and the other with compiler optimisation
-enabled. If you can install DUMB system-wide so that your projects, and other
-people's, can simply #include <dumb.h> or <aldumb.h> and link with libraries
-by simple name with no path, then that is ideal.
-
-If you successfully port DUMB to a new platform, please let me know!
-
-
-****************************
-*** The example programs ***
-****************************
-
-
-Three example programs are provided. On DOS and Windows, you can find them in
-the examples subdirectory. On other systems they will be installed system-
-wide.
-
-dumbplay
-   This program will only be built if you have Allegro. Pass it the filename
-   of an IT, XM, S3M or MOD file, and it will play it. It's not a polished
-   player with real-time threading or anything - so don't complain about it
-   stuttering while you use other programs - but it does show DUMB's fidelity
-   nicely. You can control the playback quality by editing dumb.ini, which
-   must be in the current working directory. (This is a flaw for systems
-   where the program is installed system-wide, but it is non-fatal.) Have a
-   look at the examples/dumb.ini file for further information.
-
-dumbout
-   This program does not need Allegro. You can use it to stream an IT, XM,
-   S3M or MOD file to raw PCM. This can be used as input to an encoder like
-   oggenc (with appropriate command-line options), or it can be sent to a
-   .pcm file which can be read by any respectable waveform editor. This
-   program is also convenient for timing DUMB. Compare the time it takes to
-   render a module with the module's playing time! dumbout doesn't try to
-   read any configuration file; the options are set on the command line.
-
-dumb2wav
-   This program is much the same as dumbout, but it writes a .wav file with
-   the appropriate header. Thanks go to Chad Austin for this useful tool.
-
-
-*********************************************
-*** Downloading music or writing your own ***
-*********************************************
-
-
-If you would like to compose your own music modules, then this section should
-help get you started.
-
-The best programs for the job are the trackers that pioneered the file
-formats:
-
-   Impulse Tracker - IT files - http://www.lim.com.au/ImpulseTracker/
-   Fast Tracker II - XM files - http://www.fasttracker2.com/
-   Scream Tracker 3 - S3M files - No official site known, please use Google
-
-MOD files come from the Amiga; I do not know what PC tracker to recommend for
-editing these. If you know of one, let me know! In the meantime, I would
-recommend using a more advanced file format. However, don't convert your
-existing MODs just for the sake of it.
-
-Fast Tracker II is Shareware. It offers a very flashy interface and has a
-game embedded, but the IT file format is more powerful and better defined. By
-all means try them both and see which you prefer; it is largely a matter of
-taste (and, in some cases, religion). Impulse Tracker and Scream Tracker 3
-are Freeware, although you can donate to Impulse Tracker and receive a
-slightly upgraded version. DUMB is likely to be at its best with IT files.
-
-These editors are DOS programs. Users of DOS-incapable operating systems may
-like to try ModPlug Tracker, but should read docs/modplug.txt before using it
-for any serious work. If you use a different operating system, or if you know
-of any module editors for Windows that are more faithful to the original
-trackers' playback, please give me some links so I can put them here!
-
-   ModPlug Tracker - http://www.modplug.com/
-
-If you have an x86 Linux system with VGA-compatible hardware (which covers
-all PC graphics cards I've ever seen), you should be able to get Impulse
-Tracker running with DOSEMU. You will have to give it access to the VGA ports
-and run it in a true console, as it will not work with the X-based VGA
-emulation. I personally added the SB16 emulation to DOSEMU, so you can even
-use filters! However, it corrupts samples alarmingly often when saving on my
-system - probably a DOSEMU issue. If you set this up, I am curious to know
-whether it works for you.
-
-   DOSEMU - http://www.dosemu.org/
-
-BEWARE OF WINAMP! Although it's excellent for MP3s, it is notorious for being
-one of the worst module players in existence; very many modules play wrongly
-with it. There are plug-ins available to improve Winamp's module support, for
-example WSP.
-
-   Winamp - http://www.winamp.com/
-   WSP - http://www.spytech.cz/index.php?sec=demo
-
-(There is a Winamp plug-in that uses DUMB, but it is unreliable. If anyone
-would like to work on it, please get in touch.)
-
-While I am at it I should also point out that Winamp is notorious for
-containing security flaws. Install it at your own risk, and if it is your
-work computer, check with your boss first!
-
-Samples and instruments are the building blocks of music modules. You can
-download samples at
-
-   http://www.tump.net/
-
-If you would like to download module files composed by other people, check
-the following sites:
-
-   http://www.modarchive.com/
-   http://www.scene.org/
-   http://www.tump.net/
-   http://www.homemusic.cc/main.php
-   http://www.modplug.com/
-
-Once again, if you know of more sites where samples or module files are
-available for download, please let me know.
-
-If you wish to use someone's music in your game, please respect the
-composer's wishes. In general, you should ask the composer. Music that has
-been placed in the Public Domain can be used by anyone for anything, but it
-wouldn't do any harm to ask anyway if you know who the author is. In many
-cases the author will be thrilled, so don't hesitate!
-
-A note about converting modules from one format to another, or converting
-from MIDI: don't do it, unless you are a musician and are prepared to go
-through the file and make sure everything sounds the way it should! The
-module formats are all slightly different, and MIDI is very different;
-converting from one format to another will usually do some damage.
-
-Instead, it is recommended that you allow DUMB to interpret the original file
-as it sees fit. DUMB may make mistakes (it does a lot of conversion on
-loading), but future versions of DUMB will be able to rectify these mistakes.
-On the other hand, if you convert the file, the damage is permanent.
-
-
-***********************
-*** Contact details ***
-***********************
-
-
-If you have trouble with DUMB, or want to contact me for any other reason, my
-e-mail address is given below. Please do get in touch, even if I appear to
-have disappeared!
-
-If you wish to chat online about something, perhaps on IRC, that can most
-likely be arranged. Send me an e-mail.
-
-
-******************
-*** Conclusion ***
-******************
-
-
-This is the conclusion.
-
-
-Ben Davis
-entheh@users.sf.net