Blitz3D+ Command Reference

PlayMusic ( midifile$ )

Parameters

midifile$ - path to the music file to play

Description

Plays a music file straight from disk and returns a channel handle.

There is no separate load step: you hand it a filename and it starts playing. That is the point of the command - a three-minute track never has to sit in memory the way a LoadSound effect does. A .mid or .midi file is handed to the Windows MIDI sequencer, which plays it from the file; anything else goes through the same WAV decoding as LoadSound.

Keep the returned channel handle. It is the only way to stop the track when the player leaves the level, to hold it with PauseChannel while a menu is open, or to ask ChannelPlaying whether it has ended so you can start the next one.

Because nothing is preloaded, the file is opened and read every time you call this, so starting a track mid-action can cause a brief stutter while the disk is hit. Kick music off during a load screen or a menu, not in the middle of a firefight. Where you need instant, gapless repetition, load the audio with LoadSound, mark it with LoopSound and use PlaySound instead.

It returns 0 if the file is missing or cannot be played. The channel it gives back for a MIDI file is driven by the system sequencer, which supports stopping, pausing and resuming but ignores ChannelVolume, ChannelPan and ChannelPitch.

See also: StopChannel, PauseChannel, ChannelPlaying, PlaySound, LoopSound.

Example

; PlayMusic Example
; -----------------

Graphics 640,480,0,2
SetBuffer BackBuffer()

; PlayMusic streams a music file straight from disk and returns a
; channel. Unlike LoadSound (which loads the whole sound into memory
; up front), the file is read again on every PlayMusic call - ideal
; for long tunes that would waste memory as samples.
music=PlayMusic("media/tune1.mid")

paused=0

While Not KeyDown(1)

    ; P pauses and R resumes the music channel
    If KeyHit(25) And paused=0 Then
        PauseChannel music
        paused=1
    End If
    If KeyHit(19) And paused=1 Then
        ResumeChannel music
        paused=0
    End If

    ; Space restarts the tune from the top - PlayMusic reads the
    ; file from disk again and returns a new channel
    If KeyHit(57) Then
        StopChannel music
        music=PlayMusic("media/tune1.mid")
        paused=0
    End If

    Cls

    Text 0,0,"P: pause   R: resume   Space: restart tune   Esc: exit"
    Text 0,30,"music=PlayMusic(media/tune1.mid) -> channel "+music

    If paused Then
        Color 255,180,80
        Text 320,220,"MUSIC PAUSED",True
    Else
        Color 80,255,80
        Text 320,220,"MUSIC STREAMING FROM DISK",True
    End If

    Color 255,255,255
    Text 0,400,"PlayMusic = stream from disk each call (music, long tracks)"
    Text 0,420,"LoadSound = load into memory once, play many times (effects)"

    Flip

Wend

StopChannel music

End

Index