File: mixer.rsd

package info (click to toggle)
ruby-sdl 2.2.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, bullseye, buster, sid, stretch
  • size: 1,544 kB
  • ctags: 1,359
  • sloc: cpp: 7,598; ansic: 4,498; ruby: 2,246; makefile: 106; sh: 102
file content (940 lines) | stat: -rw-r--r-- 19,098 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
= Audio
* ((<Audio subsystem outline>))
* ((<Audio Format>))
* ((<SDL::Mixer>))
* ((<SDL::Mixer::Wave>))
* ((<SDL::Mixer::Music>))
* Audio methods
TOC

== Audio subsystem outline
SDL has portable and low-level audio playback system. 
Because this system is too low-level to use from Ruby,
you can use only SDL_mixer functions from Ruby.
So you should install SDL_mixer before using audio playback.

Due to popular demand, here is a simple multi-channel audio mixer. It supports 8 channels of 16 bit
stereo audio, plus a single channel of music, mixed by the popular MikMod MOD, Timidity MIDI and SMPEG
MP3 libraries.

The process of mixing MIDI files to wave output is very CPU intensive, so if playing regular WAVE files
sound great, but playing MIDI files sound choppy, try using 8-bit audio, mono audio, or lower
frequencies.

To play MIDI files, you'll need to get a complete set of GUS patches from:
((<Timidity GUS Patches|URL:http://www.libsdl.org/projects/mixer/timidity/timidity.tar.gz>))
and unpack them in /usr/local/lib under UNIX, and C:\ under Win32.


== Available audio formats

Ruby/SDL supports playing music and sound samples from the following formats:
- WAVE/RIFF (.wav)
- AIFF (.aiff)
- VOC (.voc)
- MOD (.mod .xm .s3m .669 .it .med and more) using included mikmod
- MIDI (.mid) using timidity or native midi hardware
- OggVorbis (.ogg) requiring ogg/vorbis libraries on system
- MP3 (.mp3) requiring SMPEG library on system

Some reports from Windows users say that programs playing
MP3 sometimes hung up, so please don't play MP3 on Ruby/SDL.

== SDL::Mixer
Module for audio playback subsystem.

== SDL::Mixer::Wave
Class for sound samples. Ruby/SDL can play those samples with multi-channel.
Support formats are WAVE, AIFF, RIFF, OGG, VOC.

== SDL::Mixer::Music
Class for audio data.
Suppor formats are WAVE, MOD, MIDI, OGG, MP3.

== Audio methods
%%%
NAME open
MOD Mixer
TYPE .
PURPOSE Initialize the mixer API.

PROTO
open(frequency=Mixer::DEFAULT_FREQUENCY,format=Mixer::DEFAULT_FORMAT,cannels=Mixer::DEFAULT_CHANNELS,chunksize=4096)

DESC
Initialize the mixer API.
This must be called before using other functions in this library.
SDL must be initialized with SDL::INIT_AUDIO before this call. $[frequency]
 would be 44100 for 44.1KHz, which is CD audio rate. Most games use 22050, 
because 44100 requires too much CPU power on older computers.
$[chunksize] is the size of each mixed sample. The smaller this is the more your hooks will be called. If
make this too small on a slow system, sound may skip. If made to large, sound effects will lag behind the
action more. You want a happy medium for your target computer. You also may make this 4096, or larger, if
you are just playing music. SDL::Mixer::CHANNELS(8)
 mixing channels will be allocated by default. 

$[format] are the values listed there:

:SDL::Mixer::FORMAT_U8
    Unsigned 8-bit samples
:SDL::Mixer::FORMAT_S8
    Signed 8-bit samples
:SDL::Mixer::FORMAT_U16LSB
    Unsigned 16-bit samples, in little-endian byte order
:SDL::Mixer::FORMAT_S16LSB
    Signed 16-bit samples, in little-endian byte order
:SDL::Mixer::FORMAT_U16MSB
    Unsigned 16-bit samples, in big-endian byte order
:SDL::Mixer::FORMAT_S16MSB
    Signed 16-bit samples, in big-endian byte order
:SDL::Mixer::FORMAT_U16
    same as FORMAT_U16LSB (for backwards compatability probably)
:SDL::Mixer::FORMAT_S16
    same as FORMAT_S16LSB (for backwards compatability probably)
:SDL::Mixer::FORMAT_U16SYS
    Unsigned 16-bit samples, in system byte order
:SDL::Mixer::FORMAT_S16SYS
    Signed 16-bit samples, in system byte order

SDL::DEFAULT_FORMAT is SDL::Mixer::FORMAT_S16SYS.

$[channels] is number of sound channels in output.
Set to 2 for stereo, 1 for mono. This has nothing to do with mixing channels.
Mixer::DEFAULT_CHANNELS is 2.

NOTES
If you observe sound skipping and delaying, you may change some parameters to
resolve such problems. 
Please try to change $[frequency], $[chunksize] and $[format] parameter.

EXAMPLE
# start SDL with audio support
SDL.init(SDL::INIT_AUDIO)
# 44.1KHz, signed 16bit, system byte order, stereo audio
# using 1024 byte chunksize
SDL::Mixer.open(44100, SDL::Mixer::DEFAULT_FORMAT, 2, 1024)

EXCEPTION *

SEEALSO
Mixer.spec
Mixer.allocate_channels

%%
NAME spec
MOD Mixer
TYPE .
PURPOSE Get the actual audio format in use by the opened audio device
RVAL [Integer, UINT, Integer]

PROTO
spec

DESC
Returns the actual audio format in use by the opened audio device.
This may or may not match the parameters you passed to @[Mixer.open].
Return value is array of three elements: [frequency, format, channels].

EXAMPLE
frequency, format, channels = SDL::Mixer.spec
format_str = case format
when SDL::Mixer::AUDIO_U8 then "U8"
when SDL::Mixer::AUDIO_S8 then "S8"
when SDL::Mixer::AUDIO_U16LSB then "U16LSB"
when SDL::Mixer::AUDIO_S16LSB then "S16LSB"
when SDL::Mixer::AUDIO_U16MSB then "U16MSB"
when SDL::Mixer::AUDIO_S16MSB then "S16MSB"
end

printf "frequency=%dHz format=%s channels=%d", frequency, format_str, channels

EXCEPTION *

SEEALSO
Mixer.open

%%
NAME driver_name
MOD Mixer
TYPE .
PURPOSE Gets the audio device name
RVAL String

PROTO
driver_name
driverName

DESC
Returns the opened audio device name as String.

EXCEPTION
Raises @[Error] if audio playback system is not @[opened|Mixer.open] yet.

SEEALSO
Mixer.open

%%
NAME load
MOD Mixer::Wave
TYPE .
PURPOSE Load file for use as a sample.
RVAL Mixer::Wave

PROTO
load(filename)

DESC
Load file for use as a sample and returns the instance of @[Mixer::Wave].
$[filename] is name of wave file to use.
This can load WAVE, AIFF, RIFF, OGG, and VOC files.

NOTES
You must call @[Mixer.open] before calling this method.
It must know the output characteristics so it can convert the sample for playback, it does
this conversion at load time. Therefore you should pay attention to memory consumption.

EXCEPTION *

%%
NAME load_from_io
MOD Mixer::Wave
TYPE .
PURPOSE Read IO object for use as a sample.
RVAL Mixer::Wave

PROTO
load_from_io(io)
loadFromIO(io)

DESC
Read from Ruby's IO object (IO, StringIO or other objects with read, tell, rewind)
and returns the instance of @[Mixer::Wave].
This can read WAVE, AIFF, RIFF, OGG, and VOC files.

NOTES
You must call @[Mixer.open] before calling this method.
It must know the output characteristics so it can convert the sample for playback, it does
this conversion at load time. Therefore you should pay attention to memory consumption.

EXCEPTION *

%%
NAME destroy
MOD Mixer::Wave
TYPE #
PURPOSE Frees an audio chunk.

PROTO
destroy

DESC
Frees an audio chunk previously loaded.
If this method is called, all operations are forbidden.

SEEALSO
Mixer::Wave#destroyed?

%%
NAME destroyed?
MOD Mixer::Wave
TYPE #
PURPOSE Returns whether an audio chunk is destroyed.
RVAL true/false

PROTO
destroyed?

DESC
Returns whether au audio chunk is destroyed by
@[Mixer::Wave#destroy]

SEEALSO
Mixer::Wave#destroy

%%
NAME load
MOD Mixer::Music
TYPE .
PURPOSE Load music file.
RVAL Mixer::Music
nn
PROTO
load(filename)

DESC
Load music file to use and returns a instance of @[Mixer::Music].
$[filename] is a name of music file to use.
This can load WAVE, MOD, MIDI, OGG, MP3, and any file that you use a command to
play with.

NOTES
Need SMPEG library to load MP3.

EXCEPTION *

%%
NAME load_from_string
MOD Mixer::Music
TYPE .
PURPOSE Convert string into music data.
RVAL Mixer::Music

PROTO
load_from_string(str)
loadFromString(str)

DESC
Convert $[str] string into music data and returns a instance of @[Mixer::Music].
This can load WAVE, MOD and OGG.

NOTES
In this method, copy $[str] and store it in returned object.
Therefore this method may cause the large memory consumption.

On Windows, it may be impossible to use this method.

EXCEPTION *

%%
NAME destroy
MOD Mixer::Music
TYPE #
PURPOSE Frees an music data.

PROTO
destroy

DESC
Frees an music data previously loaded.
If this method is called, all operations are forbidden.

SEEALSO
Mixer::Music#destroyed?
Mixer::Wave#destroy

%%
NAME destroyed?
MOD Mixer::Music
TYPE #
PURPOSE Returns whether an music data is destroyed.
RVAL true/false

PROTO
destroyed?

DESC
Returns whether a music data is destroyed by
@[Mixer::Music#destroy]

SEEALSO
Mixer::Music#destroy
Mixer::Wave#destroyed?

%%
NAME set_volume
MOD Mixer::Wave
TYPE #
PURPOSE Set volume 

PROTO
set_volume(volume)
setVolume(volume)

DESC
Set wave volume to $[volume]. $[volume] should be in 0..128.

%%
NAME allocate_channels
MOD Mixer
TYPE .
PURPOSE Set the number of channels to mix
RVAL Integer

PROTO
allocate_channels(num_channels)
allocateChannels(num_channels)

DESC
Set the number of channels being mixed. This can be called
multiple times, even with sounds playing. If numchans is less
than the current number of channels, then the higher channels
will be stopped, freed, and therefore not mixed any longer. It's
probably not a good idea to change the size 1000 times a second
though.

NOTES
passing in zero ((*will*)) free all mixing
channels, however music will still play.

RET
Returns the number of channels allocated.

EXAMPLE
# allocate 16 mixing channels
SDL::Mixer.allocate_channels(16)

%%
NAME set_volume
MOD Mixer
TYPE .
PURPOSE Set the mix volume of a channel
RVAL Integer

PROTO
set_volume(channel, volume)
setVolume(channel, volume)

DESC
Set the $[volume] for any allocated $[channel]. 
If $[channel] is -1 then
all channels at are set at once. The volume is applied during
the final mix, along with the sample volume. So setting this
volume to 64 will halve the output of all samples played on the
specified channel. All channels default to a volume of 128,
which is the max. Newly allocated channels will have the max
volume set, so setting all channels volumes does not affect
subsequent channel allocations.

RET
Returns current volume of the channel. If channel is -1, the
average volume is returned.

SEEALSO
Mixer::Wave#set_volume
Mixer.set_volume_music

%%
NAME play_channel
MOD Mixer
TYPE .
PURPOSE Play loop
RVAL Integer

PROTO
play_channel(channel, wave, loops)
playChannel(channel, wave, loops)

DESC
Play $[wave](instance of @[Mixer::Wave]  on $[channel], or 
if $[channel] is -1, pick the first free
unreserved channel. The sample will play 
for $[loops]+1 number of
times, unless stopped by halt, or fade out, or setting a new
expiration time of less time than it would have originally taken
to play the loops, or closing the mixer.
if $[loops] is -1, loops infinitely.

RET
the channel the sample is played on.

EXAMPLE
# play sample on first free unreserved channel
# play it exactly once through
SDL::Mixer.play_channel(-1, sample, 0)

SEEALSO
Mixer.play_channel_timed
Mixer.fade_in_channel
Mixer.halt
Mixer.expire

%%
NAME play_channel_timed
MOD Mixer
TYPE .
PURPOSE Play loop and limit by time
RVAL Integer

PROTO
play_channel_timed(channel, wave, loops, ticks)
playChannelTimed(channel, wave, loops, ticks)

DESC
If the $[wave] is long enough and has enough $[loops] then the
sample will stop after $[ticks] milliseconds. Otherwise this
function is the same as @[Mixer.play_channel].

EXAMPLE
# play sample on first free unreserved channel
# play it for half a second
SDL::Mixer.play_channel(-1, sample, -1, 500)

SEEALSO
Mixer.play_channel
Mixer.fade_in_channel_timed
Mixer.fade_out
Mixer.halt
Mixer.expire

%%
NAME fade_in_channel
MOD Mixer
TYPE .
PURPOSE Play loop with fade in
RVAL Integer

PROTO
fade_in_channel(channel, wave, loops, ms)
fadeInChannel(channel, wave, loops, ms)

DESC
Play $[wave] on $[channel] with fade in.
The channel volume starts at 0 and fades up to full volume over
$[ms] milliseconds of time. The sample may end before the fade-in
is complete if it is too short or doesn't have enough loops.

Otherwise this function is the same as @[Mixer.play_channel].

EXAMPLE
# play sample on first free unreserved channel
# play it exactly 3 times through
# fade in over one second
SDL::Mixer.fade_in_channel(-1, sample, 2, 1000)

SEEALSO
Mixer.play_channel
Mixer.fade_in_channel_timed
Mixer.fading
Mixer.fade_out
Mixer.halt
Mixer.expire

%%
NAME fade_in_channel_timed
MOD Mixer
TYPE .
PURPOSE Play loop with fade in and limit by time
RVAL Integer

PROTO
fade_in_channel_timed(channel, wave, loops, ms, ticks)
fadeInChannelTimed(channel, wave, loops, ms, ticks)

DESC
If the sample is long enough and has enough loops then the
sample will stop after ticks milliseconds. Otherwise this
method is the same as @[Mixer.play_channel_timed].

SEEALSO
Mixer.play_channel_timed
Mixer.fade_in_channel
Mixer.fading
Mixer.fade_out
Mixer.halt
Mixer.expire

%%
NAME pause
MOD Mixer
TYPE .
PURPOSE Pause the channel

PROTO
pause(channel)

DESC
Pause $[channel], or all playing channels if -1 is passed in. You
may still $[halt|Mixer.halt] a paused channel.

EXAMPLE
# pause all sample playback
SDL::Mixer.pause(-1)

SEEALSO
Mixer.resume
Mixer.pause?
Mixer.halt

%%
NAME resume
MOD Mixer
TYPE .
PURPOSE Resume a paused channel

PROTO
resume(channel)

DESC
Unpause $[channel], or all playing and paused channels if -1 is
passed in.

SEEALSO
Mixer.pause
Mixer.pause?

%%
NAME halt
MOD Mixer
TYPE .
PURPOSE Stop playing on a channel

PROTO
halt(channel)

DESC
Halt channel playback, or all channels if -1 is passed in.
Any callback set by Mix_ChannelFinished will be called.

SEEALSO
Mixer.expire
Mixer.fade_out

%%
NAME expire
MOD Mixer
TYPE .
PURPOSE Change the timed stoppage of a channel
RVAL Integer

PROTO
expire(channel, ticks)

DESC
Halt $[channel] playback, or all channels 
if -1 is passed in, after $[ticks] milliseconds.

RET
Returns the number of channels set to expire. Whether or not they
are active.

EXAMPLE
# halt playback on all channels in 2 seconds
SDL::Mixer.expire(-1, 2000)

SEEALSO
Mixer.halt
Mixer.fade_out

%%
NAME fade_out
MOD Mixer
TYPE .
PURPOSE Stop playing channel after timed fade out
RVAL Integer

PROTO
fade_out(channel, ms)
fadeOut(channel, ms)

DESC
Gradually fade out which $[channel]
 over $[ms] milliseconds starting
from now. The channel will be halted after the fade out is
completed. Only channels that are playing are set to fade out,
including paused channels. 

RET
Returns the number of channels set to fade out.

EXAMPLE
# fade out all channels to finish 3 seconds from now
printf "starting fade out of %d channels", SDL::Mixer.fade_out(-1, 3000)

SEEALSO
Mixer.fade_in_channel
Mixer.fade_in_channel_timed
Mixer.fading

%%
NAME play?
MOD Mixer
TYPE .
PURPOSE Get the active playing status of a channel
RVAL true/false

PROTO
play?(channel)

DESC
Returns true if $[channel] is playing, otherwise
returns false.

SEEALSO
Mixer.pause?
Mixer.fading
Mixer.play_channel
Mixer.pause

%%
NAME playing_channels
MOD Mixer
TYPE .
PURPOSE Get the number of active playing channels
RVAL Integer

PROTO
playing_channels
playingChannels

DESC
Returns the number of playing.

SEEALSO
Mixer.pause?
Mixer.fading
Mixer.play_channel
Mixer.pause

%%
NAME pause?
MOD Mixer
TYPE .
PURPOSE Get the pause status of a channel
RVAL true/false

PROTO
pause?(channel)

DESC
Returns true if $[channel] is paused, otherwise 
returns false.

SEEALSO
Mixer.play?
Mixer.pause
Mixer.resume

%%
NAME fading
MOD Mixer
TYPE .
PURPOSE Get the fade status of a channel
RVAL Integer

PROTO
fading(which)

DESC
Tells you if which $[channel] is fading in, out, or not. Does not
tell you if the channel is playing anything, or paused, so you'd
need to test that separately.
Returns the fading status:
* SDL::Mixer::FADING_OUT
* SDL::Mixer::FADING_IN
* SDL::Mixer::NO_FADING

SEEALSO
Mixer.play?
Mixer.pause?
Mixer.fade_in_channel
Mixer.fade_in_channel_timed
Mixer.fade_out

%%
NAME play_music
MOD Mixer
TYPE .
PURPOSE Play music, with looping

PROTO
play_music(music, loops)
playMusic(music, loops)

DESC
Play the loaded $[music]
$[loops] times through from start to finish.
The previous music will be halted, or if fading out it waits
(blocking) for that to finish.

EXCEPTION *

SEEALSO
Mixer.fade_in_music

%%
NAME fade_in_music
vMOD Mixer
TYPE .
PURPOSE Play music, with looping, and fade in

PROTO
fade_in_music(music, loops, ms)
fadeInMusic(music, loops, ms)

DESC
Fade in over $[ms] milliseconds of time, 
the loaded $[music], playing
it $[loops] times through from start to finish.
The fade in effect only applies to the first loop.
Any previous music will be halted, or if it is fading out it
will wait (blocking) for the fade to complete.

EXCEPTION *

SEEALSO
Mixer.play_music

%%
NAME set_volume_music
MOD Mixer
TYPE .
PURPOSE Set music volume

PROTO
set_volume_music(volume)
setVolumeMusic(volume)

DESC
Set the volume to $[volume], if it is 0 or greater.
Setting the volume during a fade will
not work, the faders use this function to perform their effect!

SEEALSO
Mixer.fade_in_music
Mixer.fade_out_music

%%
NAME pause_music
MOD Mixer
TYPE .
PURPOSE Pause music

PROTO
pause_music
pauseMusic

DESC
Pause the music playback. You may @[halt|Mixer.halt_music]
paused music.

SEEALSO
Mixer.resume_music
Mixer.pause_music?
Mixer.halt_music

%%
NAME resume_music
MOD Mixer
TYPE .
PURPOSE Resume paused music

PROTO
resume_music
resumeMusic

DESC
Unpause the music. This is safe to use on halted, paused, and
already playing music.


SEEALSO
Mixer.pause_music
Mixer.pause_music?

%%
NAME rewind_music
MOD Mixer
TYPE .
PURPOSE Rewind music to beginning

PROTO
rewind_music
rewindMusic

DESC
Rewind the music to the start. This is safe to use on halted,
paused, and already playing music. It is not useful to rewind
the music immediately after starting playback, because it starts
at the beginning by default.

This function only works for these streams: MOD, OGG, MP3,
Native MIDI.

%%
NAME halt_music
MOD Mixer
TYPE .
PURPOSE Stop music playback

PROTO
halt_music
haltMusic

DESC
Halt playback of music. This interrupts music fader effects. 

SEEALSO
Mixer.fade_out_music

%%
NAME fade_out_music
MOD Mixer
TYPE .
PURPOSE Stop music, with fade out

PROTO
fade_out_music(ms)
fadeOutMusic(ms)

DESC
Gradually fade out the music over $[ms] milliseconds starting from
now. The music will be halted after the fade out is completed.
Only when music is playing and not fading already are set to
fade out, including paused channels.

%%
NAME play_music?
MOD Mixer
TYPE .
PURPOSE Test whether music is playing
RVAL true/false

PROTO
play_music?
playMusic?

DESC
Returns true if music is actively playing, otherwise
returns false.

SEEALSO
Mixer.pause_music?
Mixer.fading_music
Mixer.play_music

%%
NAME pause_music?
MOD Mixer
TYPE .
PURPOSE Test whether music is paused
RVAL true/false

PROTO
pause_music?
pauseMusic?

DESC
Returns true if music is paused, otherwise returns false.

SEEALSO
Mixer.play_music?
Mixer.pause_music
Mixer.resume_music

%%
NAME fading_music
MOD Mixer
TYPE .
PURPOSE Get status of current music fade activity
RVAL Integer

PROTO
fading_music
fadingMusic

DESC
Tells you if music is fading in, out, or not at all. Does not
tell you if the channel is playing anything, or paused, so you'd
need to test that separately.

return value is one of follwoing:
* SDL::Mixer::FADING_OUT
* SDL::Mixer::FADING_IN
* SDL::Mixer::NO_FADING

SEEALSO
Mixer.fading
Mixer.pause_music?
Mixer.play_music?
Mixer.fade_out_music