annotate README @ 474:c66080364dff

Most decoders now report total sample play time, now. Technically, this breaks binary compatibility with the 1.0 branch, since it extends the Sound_Sample struct, but most (all?) programs are just passing pointers allocated by SDL_sound around, and might be okay. Source-level compatibility is not broken...yet! :) --ryan. -------- Original Message -------- Subject: SDL_sound patch: Finding total length of time of sound file. Date: Sun, 26 Jan 2003 09:31:17 -0800 (PST) Hi Ryan, I am working with Eric Wing and helping him modify SDL_sound. AS part of our efforts in improving and enhancing SDL_sound, we like to submit this patch. We modified the codecs to find the total time of a sound file. Below is the explanation of the patch. The patch is appended as an attachment to this email. * MOTIVATION: We needed the ability to get the total play time of a sample (And we noticed that we're not the only ones). Since SDL_sound blocks direct access to the specific decoders, there is no way for a user to know this information short of decoding the whole thing. Because of this, we believe this will be a useful addition, even though the accuracy may not be perfect (subject to each decoder) or the information may not always be available. * CONTRIBUTORS: Wesley Leong (modified the majority of the codecs and verified the results) Eric Wing (showed everyone how to do modify codec, modified mikmod) Wang Lam (modified a handful of codecs, researched into specs and int overflow) Ahilan Anantha (modified a few codecs and helped with integer math) * GENERAL ISSUES: We chose the value to be milliseconds as an Sint32. Milliseconds because that's what Sound_Seek takes as a parameter and -1 to allow for instances/codecs where the value could not be determined. We are not sure if this is the final convention you want, so we are willing to work with you on this. We also expect the total_time field to be set on open and never again modified by SDL_sound. Users may access it directly much like the sample buffer and buffer_size. We thought about recomputing the time on DecodeAll, but since users may seek or decode small chunks first, not all the data may be there. So this is better done by the user. This may be good information to document. Currently, all the main codecs are implemented except for QuickTime.
author Ryan C. Gordon <icculus@icculus.org>
date Sat, 08 May 2004 08:19:50 +0000
parents 41412aa092d1
children 50bb9a6cebfe
rev   line source
78
8b7d48449ad1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
1 SDL_sound. An abstract soundfile decoder.
8b7d48449ad1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
2
256
c6b7f7999a0e Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 253
diff changeset
3 SDL_sound is a library that handles the decoding of several popular sound file
c6b7f7999a0e Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 253
diff changeset
4 formats, such as .WAV and .MP3. It is meant to make the programmer's sound
c6b7f7999a0e Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 253
diff changeset
5 playback tasks simpler. The programmer gives SDL_sound a filename, or feeds
c6b7f7999a0e Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 253
diff changeset
6 it data directly from one of many sources, and then reads the decoded
c6b7f7999a0e Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 253
diff changeset
7 waveform data back at her leisure. If resource constraints are a concern,
c6b7f7999a0e Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 253
diff changeset
8 SDL_sound can process sound data in programmer-specified blocks. Alternately,
c6b7f7999a0e Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 253
diff changeset
9 SDL_sound can decode a whole sound file and hand back a single pointer to the
c6b7f7999a0e Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 253
diff changeset
10 whole waveform. SDL_sound can also handle sample rate, audio format, and
c6b7f7999a0e Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 253
diff changeset
11 channel conversion on-the-fly and behind-the-scenes, if the programmer
c6b7f7999a0e Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 253
diff changeset
12 desires.
c6b7f7999a0e Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 253
diff changeset
13
c6b7f7999a0e Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 253
diff changeset
14 Please check the website for the most up-to-date information about SDL_sound:
232
34000a50353b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 228
diff changeset
15 http://icculus.org/SDL_sound/
78
8b7d48449ad1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
16
239
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
17 SDL_sound _REQUIRES_ Simple Directmedia Layer (SDL) to function, and cannot
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
18 be built without it. You can get SDL from http://www.libsdl.org/. SDL_sound
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
19 has only been tried with the SDL 1.2 series, but may work on older versions.
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
20 Reports of success or failure are welcome.
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
21
232
34000a50353b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 228
diff changeset
22 Some optional external libraries that SDL_sound can use and where to find them:
416
41412aa092d1 Added Borland C++ info, other revisions.
Ryan C. Gordon <icculus@icculus.org>
parents: 319
diff changeset
23 SMPEG (used to decode MP3s): http://icculus.org/smpeg/
41412aa092d1 Added Borland C++ info, other revisions.
Ryan C. Gordon <icculus@icculus.org>
parents: 319
diff changeset
24 libvorbisfile (used to decode OGGs): http://www.xiph.org/ogg/vorbis/
239
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
25 libFLAC (used to decode FLACs): http://flac.sourceforge.net/
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
26 libModPlug (used to decode MODs, etc): http://modplug-xmms.sourceforge.net/
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
27 libMikMod (used to decode MODs, etc, too): http://www.mikmod.org/
232
34000a50353b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 228
diff changeset
28
319
4a2cd7d4aa06 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 264
diff changeset
29 Experimental QuickTime support for the Mac is included, but has not been
4a2cd7d4aa06 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 264
diff changeset
30 integrated with the build system, and probably doesn't work with
4a2cd7d4aa06 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 264
diff changeset
31 QuickTime for Windows.
4a2cd7d4aa06 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 264
diff changeset
32
232
34000a50353b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 228
diff changeset
33 These external libraries are OPTIONAL. SDL_sound will build and function
34000a50353b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 228
diff changeset
34 without them, but various sound file formats are not supported unless these
34000a50353b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 228
diff changeset
35 libraries are available. Unless explicitly disabled during initial build
239
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
36 configuration, SDL_sound always supports these file formats internally:
232
34000a50353b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 228
diff changeset
37
239
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
38 - Microsoft .WAV files (uncompressed and MS-ADPCM encoded).
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
39 - Creative Labs .VOC files
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
40 - Shorten (.SHN) files
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
41 - Audio Interchange format (AIFF) files
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
42 - Sun Audio (.AU) files
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
43 - MIDI files
264
abe472572e38 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 256
diff changeset
44 - MP3 files (internal decoder, different than the one SMPEG uses)
239
30e21a90f3b1 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 232
diff changeset
45 - Raw waveform data
232
34000a50353b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 228
diff changeset
46
34000a50353b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 228
diff changeset
47 Building/Installing:
253
6e1ee1f5be1b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 248
diff changeset
48 Please read the INSTALL document.
78
8b7d48449ad1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
49
232
34000a50353b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 228
diff changeset
50 Reporting bugs/commenting:
34000a50353b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 228
diff changeset
51 There is a mailing list available. To subscribe, send a blank email to
34000a50353b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 228
diff changeset
52 sdlsound-subscribe@icculus.org. This is the best way to get in touch with
34000a50353b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 228
diff changeset
53 SDL_sound developers.
34000a50353b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 228
diff changeset
54
253
6e1ee1f5be1b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 248
diff changeset
55 --ryan. (icculus@clutteredmind.org)
6e1ee1f5be1b Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 248
diff changeset
56
319
4a2cd7d4aa06 Updated.
Ryan C. Gordon <icculus@icculus.org>
parents: 264
diff changeset
57