Beatnik Director Xtra
musicObject Lingo Handlers Reference



Beatnik Director Xtra - musicObject Lingo Handler Reference Version 1.02
©Copyright 1998 by Headspace, Inc. All rights reserved.
Last updated: 12 November, 1998

Author: Ian Chia, with portions of this document based on the Beatnik Player DocPack 2.5.
Please report errors in this document to
xtra-bugs@headspace.com



How to read this document:

1) If you're familiar with Lingo, this reference will provide many real-world examples of how to use Beatnik effectively in your projects. Read through each method carefully, using the code examples as a basic guide for the many uses of each handler. The examples have been provided as real-world cases, ranging from courseware, to QTVR audio, gaming, internationalisation and many more.

2) If you're not familiar with Lingo, browse through this reference guide, looking particularly at the example code. The samples are designed so that you can cut-and-paste into your own projects, and adjust for your own variables. This way you can take advantage of the power of the Beatnik Xtra with minimal fuss.

Brief feature summary:

The Beatnik Xtra is ideal for Enhanced CDs, gaming, interactive courseware, backing music tracks, ShockWave and general graphic user interface audio/music. Giving you up to 32 sound channels on both Macintosh and Windows platforms, with extremely low latency performance and extremely low CPU overheads, Beatnik's performance is typically superior to using DirectX or QuickTime Music. Combining a high quality, high performance software wavetable synthesiser with a state-of-the-art audio mixer, Beatnik is able to play MIDI/RMF files with their incredible bandwidth efficiencies, as well as intermix samples within RMF, AIFF, WAV, MOD and AU files. Custom instruments for the MIDI soundbank can also be created easily with quality development tools. An optional MOA mixer mode enables Beatnik audio to be intermixed with normal Director audio including ShockWave Audio, sound playFile commands, and Flash audio etc.

Advanced features such as stereo panning, sample and song transposition, track mutes/solos, reverb effects, synchronisation with Lingo based events/animations open Director up to the world of interactive audio features not previously available.

The Beatnik Xtra adds a large number of new Lingo statements that create and communicates with Beatnik 'musicObjects.' Imagine a 'musicObject' to be a type of intelligent and invisible cast member, with an extensive list of properties that can be set or read. Like a virtual band-for-hire with its own autonomy, you control the 'musicObject' band with extensive Beatnik Lingo commands.

Each musicObject is capable of interactively playing back Rich Music Format (RMF) or MIDI files of up to 64 tracks. As well, the musicObject is compatible with AIFF, WAV, AU and MOD files, albeit without the compression, full interactivity, 40bit encrypted watermarking and digital effects advantages of the RMF format. Of course you may convert MIDI, AIFF, WAV, AU and MOD files to the RMF format using the Beatnik Convertor for Windows or the Beatnik Editor for Macintosh.

How do I use it?

You can create as many musicObject instances as you like in a Director movie. While there is also no strict limit on the number of Beatnik musicObjects instances created per Director movie, simultaneous playback is limited to eight musicObjects. If you are going to create many musicObject instances, you should be aware that for each musicObject instance there is a modest minimum amount of memory that is needed on the user's system. In addition, when a musicObject instance loads its music or audio file, that file must then be contained in the user's memory.

So, while there are no forced limitations on the number of musicObject instances created from the Beatnik Xtra, you should be careful not to create movies that make such heavy demands on the user's memory resources that it become sluggish and unbearable to use.

Before any Lingo handlers can be accessed, you must first create a instance of the Beatnik musicObject that you subsequently refer to. An instance is like a 'ghost copy' of the musicObject - all the handlers contained in the Beatnik Xtra's musicObject are automatically copied to your own created instance - thus you may call your own instance, trusting that it has been automatically imbued with new and extensive audio Lingo methods. (Using the correct Object Orientated Programming terminology, all subsequent handlers of the musicObject in this document are called 'methods' of your 'instance'.)

To have Beatnik-enabled music in your Director project, you must also include the Beatnik Xtra and the Headspace soundbank "Patches.hsb" file in your project. The Xtra can be included in the Xtra folder at the same level as the Projector, or 'opened' with the openXLib command via Lingo. You may also include the Xtra inside your Projector, but you should be aware of some issues under the 'including Xtras within Projectors' option under Director 6. The Headspace sound bank file "patches.hsb" can be located anywhere and referenced via pathname using the setSampleLibrary command, but it is recommended to keep this file in the same directory as your projector or Xtra in order to keep file management simple.

In the quick reference table below, the Beatnik Player's supported musicObject methods are divided into the following main groups:

Initializing the Xtra - Instance management
Song Control and Player Properties
Playing Individual Notes
Realtime Control of Files
General Playback State
You can click on each method name to get detailed information for that method, or you can click on one of the group headings to start reading in detail about that group of methods.

Some musicObject methods are not supported (or do not have meaning) for some of the Beatnik Player's supported file types. The columns to the right of the method column indicate which file types the methods are supported for.

Method Name
RMF
.rmf
MIDI
.mid

WAV (.wav)
AIFF (.aif)
AU (.au)
MOD (.mod)

Initializing the Xtra - Instance Management

new(xtra "beatnik") yes
yes
yes

setSampleLibrary yes
yes
yes

getSampleLibrary yes
yes
yes

setPreferredSoundChannel yes
yes
yes

setSliceSize yes
yes
yes

setReady yes
yes
yes

closeBeatnik yes
yes
yes

isReady yes
yes
yes

getErrorString yes
yes
yes

Song Control & Player Properties

fadeFromTo yes
yes
yes

fadeTo yes
yes
yes

getAutostart yes
yes
yes

pause yes
yes
yes

play yes
yes
yes

playGroovoid yes
yes
yes

setAutostart yes
yes
yes

setLoop yes
yes
yes

stop yes
yes
yes

getInfo yes
-
-

getVersion yes
-
-

Playing Individual Notes

noteOff yes
yes
-

noteOn yes
yes
-

playNote yes
yes
-

Realtime Control of Files

setChannelMute yes
yes
-

setChannelSolo yes
yes
-

setController yes
yes
-

setProgram yes
yes
-

setReverbType yes
yes
yes

setTempo yes
yes
-

setTrackMute yes
yes
-

setTrackSolo yes
yes
-

setTranspose yes
yes
-

setVolume yes
yes
yes

Obtaining Playback State Information

isPaused yes
yes
yes

isPlaying yes
yes
yes

getChannelMute yes
yes
-

getChannelSolo yes
yes
-

getController yes
yes
-

getLoop yes
yes
yes

getProgram yes
yes
-

getReverbType yes
yes
yes

getTempo yes
yes
-

getTrackMute yes
yes
-

getTrackSolo yes
yes
-

getTranspose yes
yes
-

getVolume yes
yes
yes








Initializing the Xtra - Instance management


The Beatnik audio engine's functionality is implemented within Director through the Macromedia Open Architecture as a Lingo Xtra. Rather than appearing as a new Cast Member asset type, the extensive controls for handling audio appears as new Lingo handlers, able to refer a musicObject instance. A Beatnik musicObject instance is created for each audio player, and multiple musicObjects may be created within a Director movie. Only eight musicObject instances can be played simultaneously through the audio engine however.

VERY IMPORTANT: Before any Lingo handlers can be accessed, you must first create a instance of the Beatnik musicObject that you subsequently refer to. An instance is like a 'ghost copy' of the musicObject - all the handlers contained in the Beatnik Xtra's musicObject are automatically copied to your own created instance - thus you may call your own instance, trusting that it has been automatically imbued with new and extensive audio Lingo methods.

The sample code below gives a recommended approach to creating an instance of the Beatnik musicObject.

Sample Code:

on startMovie
global groovySong

if ilk(groovySong) = #instance then stop(groovySong)
set groovySong = VOID

-- create new instance of Beatnik called "groovySong"
set groovySong = new(xtra "beatnik")
if not(objectP(groovySong))
alert("Beatnik musicObject instance creation failed")
end if

-- setup buffer size and sample library's location
setSliceSize (groovySong,5)

set bankFileName = the moviePath & "Patches.hsb"
setSampleLibrary(beatnik, bankFileName)

setReady(groovySong)

-- check to see that Beatnik initialized correctly
if not(isReady(groovySong)) then
alert "Beatnik did not initialize."
exit
end if
end startMovie

on stopMovie
global groovySong
stop (groovySong)
closeBeatnik (groovySong)
set groovySong = VOID
end stopMovie



--------------------------------------------------------------------------------

new(xtra "beatnik")

Syntax: set globalVariable = new(xtra "beatnik", booleanDTCorMOA)
Example: set myBeatnikBand = new(xtra "beatnik", false)

The new(xtra "beatnik") creates a temporary instance of the Beatnik Xtra's musicObject. By defining a global variable equal to this musicObject instance, your variable is defined as a global instance of the musicObject, with all Lingo methods inherited by your named instance.

For example, by executing: set myMIDISong = new(xtra "beatnik"), the variable myMIDISong becomes an instance of the Beatnik Xtra's musicObject and inherits all methods listed in this document relevant for controlling MIDI song. Each musicObject instance that you create will use a small amount of memory (as a 'ghost' copy of the parent musicObject). When you have finally finished with each of your musicObject instances, you should free the memory allocated to it by declaring the variable equal to VOID. eg. set myMIDISong = VOID. By stopping the musicObject, shutting it down and freeing the memory, you also will flush any remaining audio in the Beatnik audio buffers. If you fail to do this last step, the next time you create the instance, you'll momentarily hear the remaining buffered audio.

When you create an instance of the musicObject, you can specify whether it will play Direct-to-soundcard (DTC) or use the Macromedia Open Architecture's mixer (MOA). By default, new instances are created to go Direct-to-card. Specifying new(xtra "beatnik") without the second parameter is equivalent false (DTC.) The DTC mode has great advantages in response speed compared to MOA mode, as the Headspace Audio Engine has been designed to typically take up 1% of CPU time on an equivalent 100MHz Pentium processor. If you require Director audio to play simultaneously with Beatnik, creating a musicObject in MOA mode will enable this to occur, albeit with lesser performance. It is recommended that setSliceSize be set to a higher value in MOA mode so that sound breakup does not occur. You cannot have a number of instances that mix DTC or MOA mode - all instances must be set to the same mode, or silence will result. However, to effectively use Beatnik and MOA audio in your projects, you may selectively create and destroy musicObject instances at various points to take advantages of each audio mode.

Note:

The new(xtra "beatnik") statement is not optional. A musicObject instance must be created for your targetted filetype, regardless of whether it is RMF, MIDI, AIFF, WAV, AU or MOD.

Sample Code:

-- this movie has two musicObject instances.
-- the instance called "mySoundTrack" will the musicObject
-- that plays the backing music, the instance
-- called "interfaceSounds" will contain special button
-- and transition sounds created with custom samples in a RMF file.
-- you can call your own instances whatever you'd like so long
-- they are valid Lingo variable names

on startMovie
-- your instances need to be global variables to be able
-- to be referred throughout the entire movie
global mySoundTrack
global myInterfaceSounds
-- create mySoundTrack instance in Direct-to-card mode
set mySoundTrack = new(xtra "beatnik")
-- create myInterfaceSounds instance in Direct-to-card mode
set myInterfaceSounds = new(xtra "beatnik")
end startMovie

-- control of the backing music is accomplished by referring
-- to the global variable "mySoundTrack"
-- for example:
on enterFrame
global mySoundTrack
-- alters volume of the backing music
setVolume(mySoundTrack,integerVolumeLevel)
-- plays backing music
play(mySoundTrack)
end enterFrame

-- user interface sounds can be controlled by referring
-- to the global variable "interfaceSounds"
-- for example:
on mouseUp
global myInterfaceSounds
-- play on MIDI channel 16, user bank 2, program 1,
-- a middle C note at max velocity for 0.5 seconds
playNote(myInterfaceSounds,16,2,1,64,127,500)
end mouseUp

on stopMovie
global mySoundTrack
global myInterfaceSounds
stop(mySoundTrack)
stop(myInterfaceSounds)
closeBeatnik(mySoundTrack)
closeBeatnik(myInterfaceSounds)
-- declaring each musicObject instance to equal VOID will
-- free up the memory allocated for the child instance
set mySoundTrack = VOID
set myInterfaceSounds = VOID
end stopMovie


--------------------------------------------------------------------------------

setSampleLibrary

Syntax: setSampleLibrary(objectMe, "string")
Example: setSampleLibrary(beatnik, the moviePath & "patches.hsb")


The setSampleLibrary() method sets the location of the default sample library (Patches.hsb) used for the General MIDI (GM) and Special sound banks built into the Beatnik Xtra. Samples within User Instruments are not stored in the Headspace Sample Bank (Patches.hsb) but instead are encapsulated with a 40bit encrypted watermark in a Rich Music Format (rmf) file. Refer to the documentation for the Beatnik Editor for Macintosh and the Beatnik Windows Convertor for more information about creating your own custom RMF files with custom samples.

Sample Code:

-- patches.hsb file is located in the same directory
-- as the Director Projector
set bankFileName = the moviePath & "Patches.hsb"
setSampleLibrary(beatnik, bankFileName)


--------------------------------------------------------------------------------

getSampleLibrary

Syntax: getSampleLibrary(objectMe)
Example: getSampleLibrary(beatnik)


The getSampleLibrary() method finds location of the default sample library (Patches.hsb) used for the General MIDI (GM) and Special sound banks built into the Beatnik Xtra. Samples within User Instruments are not stored in the Headspace Sample Bank (.hsb) but instead are encapsulated with a 40bit encrypted watermark in a Rich Music Format (rmf) file. getSampleLibrary() is designed primarily for ShockWave delivery of Beatnik content using the Beatnik Xtra - as the Patches.hsb bank would be already installed into a end user's system, one only need to check via getSampleLibrary(), if it's not available, the content provide would initiate a smart updating process. The Beatnik Xtra without the hsb bank is approximately 150K in size for both Macintosh and Windows platforms, so a requested download/upgrade would not be a strenous effort.

Sample Behaviour:

-- NO LIBRARY SET, NO BANK FOUND IN CURRENT FOLDER OR WINDOWS FOLDER:
put getSampleLibrary(beatnik)
-- Void

-- if Patches.hsb is present in system folder
put getSampleLibrary(beatnik)
-- "C:\WINDOWS\Patches.hsb"

-- Setting one explicitly
setSamplelibrary(b, "n:\beatnik\Patches.hsb")
put getSampleLibrary(beatnik)
-- "n:\beatnik\Patches.hsb"


Finding one in current folder:

set currSoundBank = getSampleLibrary(beatnik)
if voidP(currSoundBank) then
alert "Can't find a sound bank!"
exit
end if


--------------------------------------------------------------------------------

setSampleLibrary

Syntax: setSampleLibrary(objectMe, "string")
Example: setSampleLibrary(beatnik, the moviePath & "Patches.hsb")


The setSampleLibrary() method sets the location of the default sample library (Patches.hsb) used for the General MIDI (GM) and Special sound banks built into the Beatnik Xtra. Samples within User Instruments are not stored in the Headspace Sample Bank (.hsb) but instead are encapsulated with a 40bit encrypted watermark in a Rich Music Format (rmf) file. Refer to the documentation for the Beatnik Editor for Macintosh and the Beatnik Windows Convertor for more information about creating your own custom RMF files with custom samples.

Sample Code:

-- Patches.hsb file is located in the same directory
-- as the Director Projector
set bankFileName = the moviePath & "Patches.hsb"
setSampleLibrary(beatnik, bankFileName)


--------------------------------------------------------------------------------

setPreferredSoundChannel

Syntax: setPreferredSoundChannel(objectMe, integerSliceSize)
Example: setPreferredSoundChannel (beatnik,12)
setPreferredSoundChannel (beatnik,integerChannel) SetPreferredSoundChannel is only currently available when mixing through Director (that is, not Direct to Card mode). Use it to declare your sound channel of preference. By default, Beatnik will attempt to use the highest free sound channel available. You can override that preference with this call.

Note that your preference request affects all existing Beatnik instances. All of Beatnik always mixes into just one Director sound channel. You cannot keep on channel for, say, a .RMF file, and another for playing notes. This call does not guarantee that channel will be available - if it is busy, then Beatnik will seek out another channel during play time. If you need to know the actual channel in which Beatnik is playing, always check the return value from your play command (they return the actual sound channel in use).

Note:
Previous channel preference, if any, or 0 if no preference. Valid values are 0 to maxChannel for that machine (varies, but usually 4 on Windows and 8 on Mac). values outside that range have no effect. Setting zero disables preferences.



--------------------------------------------------------------------------------

setReady

Syntax: setReady(objectMe)
Example: setReady(beatnik)
Related: isReady, closeBeatnik



Initialize Beatnik Engine.



--------------------------------------------------------------------------------

closeBeatnik

Syntax: closeBeatnik(objectMe)
Example: closeBeatnik(beatnik)
Related: setReady, isReady



Closes down Beatnik Engine. Should be done when closing off a musicObject instance, and declaring the instance to be VOID. This will avoid any possible conflicts with the Director engine.



--------------------------------------------------------------------------------

isReady

Syntax: isReady(objectMe)
Example: repeat while not(isReady(beatnik))
Related: setReady, closeBeatnik



Checks to see if Beatnik musicObject instance (and its underlying Headspace Audio Engine's instance) is initialized. Returns a boolean TRUE or FALSE and can be used to poll the Headspace Audio Engine for the specified musicObject instance to determine if it's ready to play and be affected through musicObject methods, with true indicating that it is ready for playing.

Sample Code:

-- do not proceed until isReady(beatnik) is true
repeat while not(isReady(beatnik))
nothing
end repeat


--------------------------------------------------------------------------------

getErrorString

Syntax: getErrorString(objectMe,integerErrorCode)
Example: getErrorString(beatnik,errorCode)


Returns a string corresponding to the error code passed from a method. By setting the method to a variable and testing if the returned variable is zero ie. not(FALSE) (also evaluated to not equal to zero), one may proceed to an error handler.

Error Code (integer) String returned from method
0
No Error
-10
Error Bad Arguments
-11
Error File Not Found
-12
Error Initializing
-13
Error Already Initialized
-14
Error In Stream
-15
Error Not Initialized
-256
Error Unknown


Sample Code:

global errorCode
-- if myFile = "", then errorCode = -11 (ie. File Not Found)
global myFile = ""

-- sample test handler
on loadFile
set errorCode = playFile(beatnik,myFile)
if not(errorCode) then debugError
end loadFile

on debugError
global errorCode
set alertString = getErrorString(beatnik,errorCode)
alert alertString
end debugError

Song Control and Player Properties

This section describes methods useful for implementing general user interface controls, as well as controlling playback of music tracks, atmospheric soundbeds and audio transitions.



--------------------------------------------------------------------------------

fadeFromTo

Syntax: fadeFromTo(objectMe, startVolumeInteger, endVolumeInteger, [fadeTimeMilliseconds])
Example: fadeFromTo(beatnik,1,100)
Related: fadeTo


fadeFromTo will fade the volume level of the targeted file from a specified initial volume level to a specified final volume level. If the "from" volume level is much different to the current volume level of the playing file, there will be a noticeable glitch as the volume changes initially and then begins to fade. The [fadeTimeMilliseconds] parameter is optional - if not specified, the Beatnik Xtra will use a default value of 0.1 second. Although the function is termed "fade" - both fading up and fading down is easily accomplished by setting the volumes to ramp up or down. Allowed values of the volume integer are 0 to 100 inclusive. This function controls the volume output of the Xtra and is different to the MIDI channel volume Controller 7 changes.

Note:

If the targeted file is not currently playing or is in a pause state, this method will have no effect.

Sample Code:

on crescendo
global ambience
-- fade up from silence to max over 5 seconds
fadeFromTo(ambience, 1, 100, 5000)
end crescendo



--------------------------------------------------------------------------------

fadeTo

Syntax: fadeTo(objectMe, endVolumeInteger, [fadeTimeMilliseconds]))
Example: fadeTo(beatnik, 0, 2500)
Related: fadeFromTo


fadeTo will fade the volume level of the targeted file from the current volume level to a specified final volume level. The [fadeTimeMilliseconds] parameter is optional - if not specified, the Beatnik Xtra will use a default value of 0.1 second. Although the function is termed "fade" - both fading up and fading down is easily accomplished by setting the end volume to ramp up or down from the current volume level. Allowed values of the volume integer are 0 to 100 inclusive. This function controls the volume output of the Xtra and is different to the MIDI channel volume Controller 7 changes.

Note:

If the targeted file is not currently playing or is in a pause state, this method will have no effect.

Sample Code:

on fadeMusicDuringVoiceOver
global musicFile
-- 1.8 second fade down to 30% volume from current volume level
fadeTo(musicFile, 20, 1800)
end fadeMusicDuringVoiceOver



--------------------------------------------------------------------------------

getAutostart

Syntax: getAutostart(objectMe)
Example: getAutostart(beatnik)
Related: setAutostart


Returns the autostart property of the Beatnik Xtra instance. This property is set initially using the setAutostart method, or defaults to TRUE. Since the setAutostart method is useful for preloading musicObject files, you may have a number of musicObject instances that are dynamically used for preloading or playing. getAutostart may be used to query each instance for the autostart property.

Sample Code:

on checkAutoStart
global myInstance
set x = getAutostart(myInstance)
set y = isPlaying(myInstance)
set z = isPaused(myInstance)
-- if all three above properties are false, then file is stopped
-- musicObject instance has not been set to autostart
if (not(x) and not(y) and not(z) then
play(myInstance,"jungle.rmf")
end if
end checkAutoStart


--------------------------------------------------------------------------------

getInfo

Syntax: getInfo(objectMe, stringInfoFieldName)
Example: getInfo(beatnik, copyright)



Gets information about the song currently loaded by the targeted musicObject instance. The string parameter passed to this method indicates the specific field of the song information contained in an RMF file. The possible field names are listed in the table below. Field names are not case-sensitive. If no string is declared, the current version number and details of the Xtra will be returned.

Note:

This method has no meaning for file types other than RMF and will return a null string. A null string will be returned if an invalid field name is specified.

stringInfoFieldName
title performer
composer copyright
publisher use
licensee term of license
expiration date composer's notes
index


Sample Code:

on displayTrackName
global mySong
set RMFtitle = getInfo(mySong, "title")
put RMFtitle into member "textCastMember"
end displayTrackName


--------------------------------------------------------------------------------
getVersion

Syntax: getVersion(objectMe)
Example: getVersion(beatnik)
Returns a string about the version of the Beatnik Xtra, with information about Mac or Windows platform, version number and Lite or Pro edition.

Sample Code:

on checkXtraVersion
global beatnik
alert getVersion(beatnik)
end checkXtraVersion


--------------------------------------------------------------------------------

pause

Syntax: pause(objectMe, fadeTimeMillisecondsInteger)
Example: pause(beatnik)
Related: play, stop, playGroovoid, isPaused, isPlaying



Pauses the targeted file so that it may be resumed using the pause or play methods. Once a file is in pause mode, the isPaused property is set to true. The optional second parameter fadeTimeMillisecondsInteger will ensure that the song pause occurs after the milliseconds fade time specified.

Sample Code:

on mouseUp
global currentPopSong
-- toggles the pause state of my song
-- if playing, song will pause after a fade time of 0.75 seconds
-- if paused, song will restart instantly from last song position
pause (currentPopSong, 750)
-- check to see if file is paused and display "paused" graphic
if (isPaused(currentPopSong) then
set the visible of sprite 8 to TRUE
else
set the visible of sprite 8 to FALSE
end if
end mouseUp


--------------------------------------------------------------------------------

play

Syntax: play(objectMe, booleanLoopState, stringFileName)
Example: play(beatnik)
Related: pause, stop, playGroovoid, isPaused, isPlaying, setLoop, setAutostart


This method will load the specified file into memory - depending on the setAutostart status, the file will either start playing automatically, or wait till a play command is initiated. Thus by using setAutostart(objectMe, FALSE), preloading of Beatnik music and sound files can be accomplished.

When used with no second or third parameters, play will start the targeted file playing. If the targeted file is already playing, this method will be ignored. Also, if a file has been put into pause mode with the pause method, play will make the file resume playing.

Sample Code:

on mouseUp
global technoBacking
-- play current song
play(technoBacking, TRUE, the moviePath & "techdance.rmf")
go to frame "technoDancers"
end mouseUp


--------------------------------------------------------------------------------

playGroovoid

Syntax: playGroovoid(objectMe, booleanLoopState, stringNameOfGroovoid)
Example: playGroovoid(beatnik, TRUE, "Background-Clock")
Related: pause, stop, play, isPaused, isPlaying, setLoop


Similar to the play method excepting that the file to be played is a Groovoid which is contained inside the Beatnik sound bank. Groovoids are a collection of "pre-cooked" musical cues, background music, and user-interface type musical effects that comes bundled with the Beatnik Xtra.

What's so great about Groovoids?

They are always local to the user's system and so are triggered immediately. Because they are based in memory, they are useful for providing instant user-interface sounds, accompany transition effects with music cues, or provide some audio backing whilst you preload other media assets off your hard drive or CD-ROM or online ShockWave assets.
Groovoids are FREE! They are yours to use on your Director project with no strings attached. There's no need to pay any license or "drop" fees, and you never have to report usage.
There are 60 of them in the free Lite version of the Beatnik Xtra, designed for a wide variety of uses, ranging from user-interface feedback sounds to transitions, atmospheric sound beds, jingles and bumpers.
If you upgrade to the Beatnik Xtra Pro, you'll get 120 Groovoids, especially designed to give your Director project a even wider range of professional sound bites and transitions.
When used with no booleanLoopState parameter, playGroovoid will start the targeted Groovoid playing. If the targeted Groovoid is already playing, this method will be ignored. Also, if a file has been put into pause mode with the pause method, playGroovoid will make the file resume playing.

stringNameOfGroovoid

Background
Hits

Background-Beeps
Background-Clock
Background-Dubby
Background-Funky
Background-Groove2
Background-InfoPulse
Background-Latin
Background-News
Background-Piano
Background-SimpleTyping
Background-Smooth
Background-StillWaiting
Background-Teletype
Hits-BlastOff
Hits-Kicker1
Hits-Kicker2
Hits-Kicker5
Hits-LudwigVan
Hits-Magic
Hits-MysteryChime
Hits-SportsOrganCharge
Hits-ZoomAndHit

Fanfare
Miscellaneous

Fanfare-Arrival
Fanfare-Cascade
Fanfare-CorpSting1
Fanfare-Finished
Fanfare-Horserace
Fanfare-Majesty
Fanfare-Mars
Fanfare-Presenting
Fanfare-Sports
Misc-CashRegister
Misc-ThruPhoneRing

UI (User Interface)

UI-BeepClick1
UI-CarriageReturn
UI-Chimes
UI-Choice1
UI-Click1
UI-Click2
UI-Click3
UI-Click4
UI-Click5
UI-Click6
UI-Click7
UI-Click8
UI-Click9
UI-Click10
UI-Click11
UI-Click12
UI-Click13
UI-Click14
UI-Click15
UI-Click16
UI-Click17
UI-Click18
UI-Load1
UI-FunnyBeep
UI-MouseOver1
UI-MouseOver2
UI-MouseOverDrone1
UI-Notification1
UI-Notification2
UI-Notification3
UI-OpenOrClose1
UI-OpenOrClose2
UI-OpenOrClose3
UI-Question
UI-SimpleClick1
UI-SimpleClick2
UI-SystemBeep
UI-TeletypeBurst2
UI-TypeOneKey





Sample Code:

on mouseUp
global myBeatnikInstance
-- play backing groovoid as entertainment whilst we load an image off the net
setLoop(myBeatnikInstance, TRUE)
playGroovoid(myBeatnikInstance, TRUE, "Background-InfoPulse")
preloadNetThing("http://www.headspace.com/images/front/web-alive.gif"
end mouseUp
Or:

-- do 2 frame transition with Groovoid and puppetTransition
-- on first frame
on mouseUp
global myBeatnikInstance
-- play transition Groovoid
playGroovoid(myBeatnikInstance, FALSE, "Fanfare-Sports")
go to frame+1
end mouseUp

-- on next frame
on exitFrame
puppetTransition 2
go to frame+1
end exitFrame


--------------------------------------------------------------------------------

setAutoStart

Syntax: setAutoStart(objectMe,booleanStatus)
Example: setAutoStart(beatnik,FALSE)
Related: getAutostart, play


Sets the autostart property of the targeted player. The current autostart state can be obtained using the getAutoStart method. This method is useful is preloading files by initially setting setAutoStart to false, and issuing a play(instanceName, filename)command. Once the file is preloaded, subsequent playback can be initiated by a simply play(instanceName).

Important Note:

The autostart property will affect all new files that are played using the play method.

Sample Code:

on preloadTrack -- preloads voiceover1.aif without playback straightaway
global narrationTrk
setAutoStart(narrationTrk,FALSE)
play(narrationTrk,theMoviePath && "voiceover1.aif)
end preloadTrack

on mouseUp -- on button click, start voiceover
global narrationTrk
play(narrationTrk)
end mouseUp


--------------------------------------------------------------------------------

setLoop

Syntax: setLoop(objectMe, booleanLoopState)
Example: setLoop(beatnik, TRUE)
Related: getLoop


Sets the loop status of the targeted file. This can be done after a file has already been loaded. Loop state can be obtained through the musicObject using the getLoop method.

Sample Code:

on mouseUp
global mySong
-- sprite script for Song Loop button
setLoop(mySong, TRUE)
end mouseUP


--------------------------------------------------------------------------------

stop

Syntax: stop(objectMe, fadeTimeMillisecondsInteger)
Example: stop(beatnik)
Related: play, pause, playGroovoid, isPaused, isPlaying



Stops the targeted file and unloads the song from memory. Stopped files may not be resumed with the pause method. To pause files so that they may be resumed, use the pause method. The optional second parameter fadeTimeMillisecondsInteger will ensure that the song halt occurs after the milliseconds fade time specified.

Sample Code:

on enterFrame
global transAudio
-- stop music that has been playing during frame transition
stop(transAudio, 1000)
end enterFrame
Playing Individual Notes


The methods in this section control an instance of the musicObject designed to play individual note events triggered purely via Lingo. This approach is useful for applications such as music courseware where you're required to perform a sequence of discrete musical notes, or playback of simple user-interface sounds based on instrumental notes. More advanced applications include new applications for self-generative music purely through logic embodied in Lingo programming.

IMPORTANT NOTE:

For the methods in this "Playing Individual Notes" section to function correctly, a 'blank' musicObject instance must be created so that these methods can reference this instance, and the instance itself does not play any notes embedded within the targetted file. Unlike older versions of the Beatnik Player for Web browsers (versions prior to 1.3.1), you do not need a "stub.rmf". Just create an instance, and it will respond accurately to the following methods.



--------------------------------------------------------------------------------

noteOff

Syntax: noteOff(objectMe, integerMIDIChannelNum, integerNoteNum, integerVelocityNum)
Example: noteOff(stub, 16, 64, 127)
Related: noteOn, playNote, setMonophonic, getMonophonic, getNoteName


The noteOff method will switch off a note which is currently playing. In order to specify the exact note, it is necessary to specify the MIDI channel, note number, and velocity used to switch the note on. If no note is currently playing with the specified properties, this method is ignored. noteOff may also be used to turn off notes which have been turned on using the playNote method.

Syntax Variations:

noteOff(objectMe, integerMIDIChannelNum)

By only specifying a MIDI channel number, the noteOff method will switch off all notes that are currently playing on the specified MIDI channel. This only applies, however, to notes that were turned on using musicObject's noteOn method, and does not apply to notes that were turned on from inside a MIDI or RMF file. The method is still useful, however, for user interface sonification that is done entirely through scripted note playing. The noteOn/noteOff methods are only supported for RMF (.rmf) files.

Sample Code:

on mouseDown
global stub
-- play note on channel 16 Bank 1, Program 1 (piano) at velocity 120
noteOn(stub,16,1,1,64,120)
end mouseDown

on mouseUp
global stub
noteOff(stub,16,64,120) -- turn previous note off
end mouseUp

on mouseUp
global stub
noteOff(stub,16) -- turns all notes off on Channel 16
end mouseUp


--------------------------------------------------------------------------------

noteOn

Syntax: noteOn(objectMe, integerMIDIChannelNum, integerBankNum, integerProgramNum, integerNoteNum, integerVelocityNum)
Example: noteOn(stub,16,0,17,84,50)
Related: noteOff, playNote, setMonophonic, getMonophonic, getNoteName



Starts a note playing on a specified MIDI channel number, with the specified bank/program, note number and velocity. The note will continue to be sustained indefinitely unless switched off using the noteOff method.

Sample Code:

on mouseDown
global stub
-- play note on channel 16, Bank 1, Program 1 (piano) at velocity 120
noteOn(stub,16,1,1,64,120)
end mouseDown

on mouseUp
global stub
noteOff(stub,16,64,120) -- turn previous note off
end mouseUp

on mouseUp
global stub
noteOff(stub,16) -- turns all notes off on Channel 16
end mouseUp


--------------------------------------------------------------------------------

playNote

Syntax: playNote(objectMe, integerMIDIChannelNum, integerBankNumber, integerProgramNum, integerNoteNum, integerVelocityNum, integerNoteDurationMilliseconds)
Example: playNote(stub, 8, 56, 127, 1000)
Related: noteOff, noteOn, setMonophonic, getMonophonic, getNoteName


Issues a note to the specified MIDI channel, of the specified note number, velocity, and duration. It is important to remember that note duration is measured in milliseconds (1/1000th of a second) as opposed to Lingo ticks (1/60 second). Notes which are started using playNote may also be switched off using noteOff, even before their duration has expired. To do this, it is necessary to target the note using the correct MIDI channel, note number, and velocity used in the initial playNote call. Only RMF files are supported for playNote and it is highly recommended that you use the "stub.rmf" file provided.

Sample Code:

on mouseEnter
-- play a minor chord with the Special Bank's string sound
-- for one second on entering a Sprite's active area.
playNote(stub,3,1,51,64,127,1000)
playNote(stub,3,1,51,67,127,1000)
playNote(stub,3,1,51,71,127,1000)
end mouseEnter
Realtime Control of Files



Useful for implementing general user interface controls, as well as controlling playback of music tracks, atmospheric soundbeds and audio transitions, these methods provide a number of ways to control in detail the playback of RMF and MIDI music files. Used imaginatively, you may have a multitracked piece of background music that responds to user initiated events. on mouseDown, on keyDown, control of MIAWs or any other interface interaction can subtly or radically modify the background musical texture, introduce other timbral layers or sound effects, having audio cues follow onscreen objects by panning in the stereo field - and more! Besides the examples found included with this documentation, be sure to visit the Beatnik Showcase at Headspace to hear and see more cutting edge examples. Remember that the web-based Beatnik Player for Netscape and Internet Explorer has all the same capabilities as the Beatnik Xtra for Director - all methods in this and other sections have their counterparts in javascript and may be controlled through a web page.



--------------------------------------------------------------------------------

setChannelMute

Syntax: setChannelMute(objectMe, integerMIDIChannelNum, booleanMuteState)
Example: setChannelMute(beatnik,1,TRUE)
Related: getChannelMute, setChannelSolo, getChannelSolo, getTrackMute, setTrackMute, setTrackSolo, getTrackSolo


Mutes or unmutes the specified channel (1-16) based upon the boolean value used in the method. Using true will mute a channel and using false will unmute a channel. A channel's current mute status can be obtained by using the getChannelMute method. A non-standard MIDI implementation allows you to specify channel 0 (zero), which will alter all channels simultaneously.

For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation.

Note:

Only supported for RMF (.rmf) files and MIDI (.mid) files. To use wav, aiff, au or mod samples, you must convert them into RMF format. Consult the Beatnik Editor for Macintosh and Beatnik Convertor for Windows for tutorials on this topic.

Sample Code:

-- on button click, mutes voice-over on channel 1 of TV jingle song
on mouseUp
setChannelMute(TVsubmixSong,1,TRUE)
end mouseUp


--------------------------------------------------------------------------------

setChannelSolo

Syntax: setChannelSolo(objectMe, integerMIDIChannelNum, booleanSoloState)
Example: setChannelSolo(beatnik)
Related: setChannelMute, getChannelMute, getChannelSolo, getTrackMute, setTrackMute, setTrackSolo, getTrackSolo


Sets the solo status of the specified channel (1-16) based upon the boolean value used in the method. Using true will solo a channel and using false will unsolo a channel. A channel's current solo status can be obtained by using the getChannelSolo method. For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation. A non-standard MIDI implementation allows you to specify channel 0 (zero), which will alter all channels simultaneously.

Note:

Only supported for RMF (.rmf) files and MIDI (.mid) files. To use wav, aiff, au or mod samples, you must convert them into RMF format. Consult the Beatnik Editor for Mac and Beatnik Convertor for Windows for tutorials on this topic.

Sample Code:

-- multiVoiceOver instance is RMF file with seperate voiceovers
-- samples recorded on MIDI channels 1 - 6 for different languages.
-- on mouse click, we change to the next language channel

global languageChannel

on mouseUp
set languageChannel = languageChannel + 1
if languageChannel > 6 then set languageChannel = 1
setChannelSolo(multiVoiceOver,languageChannel,TRUE)
end mouseUp


--------------------------------------------------------------------------------

setController

Syntax: setController(objectMe, integerMIDIChannelNum, integerControllerChange, integerControllervalue)
Example: setController(beatnik,14,7,127)
Related: getController


"MIDI Controller Changes" are a powerful feature of controlling "on-the-fly" the software wavetable MIDI synthesiser inside the Beatnik Xtra. By familiarising yourself with MIDI Controller Change options, you may control certain synthesiser settings of a RMF or MIDI file as it's playing back. A non-standard MIDI implementation allows you to specify channel 0 (zero), which will alter all channels simultaneously.

Controller
Change No. Reset value Description
0
0
Bank select 0-2 (MSB - most significant byte.) Beatnik only responds to MSB for specified MIDI Channel
1
0
Modulation wheel (0 to 127) for specified MIDI Channel
7
127
Volume for specified MIDI Channel (Recommended valid range is 1 to 127 - using 0 will cut notes off)
10
64
Pan (For stereo field: 0 is left, 64 is center, 127 is right) for specified MIDI Channel
11
0
Expression (Note: Expression only responds to value = 127, overall volume of channel is boosted 25%) for specified MIDI Channel
64
0
Sustain Pedal for specified MIDI Channel
90
1
Reverb Type (reverb type is global - all instances are affected with current Reverb Type - specific instruments can be made 'dry' by configuration settings within the Beatnik Editor for Macintosh.)
91
14
Reverb Level (may be altered on the fly, but be aware of glitching artifacts if audio is playing.)
98
0
non registered parameter LSB (reserved.)
99
0
non registered parameter MSB (reserved.)
100
0
registered parameter LSB (reserved.)
101
0
registered parameter MSB (reserved.)


Note:

Only supported for RMF (.rmf) files and MIDI (.mid) files. To use wav, aiff, au or mod samples, you must convert them into RMF format. Consult the Beatnik Editor for Macintosh and Beatnik Convertor for Windows for tutorials on this topic.

Sample Code:

-- fade Channel 10 (drums) whilst the rest of the RMF song
-- continues at full volume
on fadeDrums
repeat with i = 127 down to 0
setController(rmfSong,10,7,i)
-- repeat loop delay for demonstration only. In real life,
-- use a threaded implementation to avoid locking user out
repeat with j = 1 to 8000
updateStage
end repeat
end repeat
end fadeDrums

Or:

-- Pan an atmospheric sound effect in 180 degree stereo field
-- in response to a user's control of a QuickTime VR panorama.
-- For a true 360 degree implementation, front and back would
-- be implemented by linking stereo pan to setVolume as well.
--
-- panPosition's valid values are integer -100 to +100
-- (this demo handler uses the same pan range as the
-- Beatnik Stereo Pan Behaviour)

on panSurroundSound panPosition
-- MIDI Controller 10 = pan, normal valid MIDI range is 0 to 127
-- following line calculates panPosition's -100 to 100
-- to MIDI Controller 10's 0 to 127 range.
set i = integer((panPosition+201)/1.5625-65)
if (i<0) then set i=0
if (i>127) then set i=127
-- Channel parameter is set to 0 to effect ALL MIDI channels
setController(atomicGeneratorSFX,0,10,i)
end panSurroundSound


--------------------------------------------------------------------------------

setProgram

Syntax: setProgram(objectMe, integerMIDIChannelNum, integerProgramNum)
Example: setProgram(beatnik,1,51)
Related: getProgram, getController, setController, playNote, noteOn, noteOff


Issues a program change (altering the 'instrumental' sound of the channel) to the specified MIDI Channel with the specified program number. There are three sound banks available in Beatnik - each bank has 128 sounds. The General MIDI (0) bank conforms to the General MIDI (GM) instrument standard, with standardised instrument numbers. The Special Bank (1) has a number of alternative sounds designed to complement the GM bank, having subtle or wilder variations to the GM sounds. Many of the instruments are mapped to the same program number so that you want simply change to the Special Bank for a quick variation on the GM sound. The User Bank (2) contains custom instruments that you create with the Beatnik Editor for Macintosh, enabling custom samples to be encapsulate as a 'virtual sampler' and synchronised to MIDI songs. Since a RMF or MIDI file has 16 instrument Channels, setProgram enables you to change each Channel to different instruments. By creating sounds for the User Bank, you may have up to 384 different instruments available for each 16 channel, in addition to a range of single key sounds available in the percussion bank (only available for Channel 10).

Variation:

setProgram(objectMe, integerMIDIChannelNum, integerBankNum, integerProgramNum)

Same as the basic setProgram method except that it is overloaded to accept a bank number as well. This makes it easy to select a specific program of a specific bank in a one-step operation. Consult the instrument list for the full list of available instruments. A non-standard MIDI implementation allows you to specify channel 0 (zero), which will alter all channels simultaneously.

Note:

Only supported for RMF (.rmf) files and MIDI (.mid) files. To use wav, aiff, au or mod samples, you must convert them into RMF format. Consult the Beatnik Editor for Macintosh and Beatnik Convertor for Windows for tutorials on this topic.

Sample Code:

-- set the Channel 2 instrument to a piano in the Special Bank
setProgram(beatnik,2,0,1,1)
playNote(beatnik,2,38,127,1000)


--------------------------------------------------------------------------------

setReverbType

Syntax: setReverbType(objectMe, integerReverbType)
Example: setReverbType(beatnik, 2)
Related: getReverbType



Used to set the reverb type for playback. Reverb is a system wide setting - multiple instances of the musicObject will all share the same reverb setting. The Beatnik Xtra Lite has a small range of reverbs - by upgrading to the Beatnik Xtra Pro, a wider range of reverbs and other digital effects are available.

Only RMF files can have reverb settings preset during authoring, which can be altered during playback with setReverbType. Be careful to always save your RMF files with a specific reverb set, unless you know that there will be several instances in your Director project and it's appropriate for them to all "inherit" the same reverb setting. The system's reverb type will change to a preset reverb type within a RMF file.. To setup reverb type during authoring for RMF files, you need to specify a reverb in the "Song Settings ..." dialog in the Beatnik Editor for Macintosh.

Note:

All supported file types (RMF, MIDI, WAV, AIFF, MOD and AU) are affected by setReverbType, making it a useful way to add dynamically controlled reverb to sample files as well as RMF and MIDI.

RMF file's user instruments can have reverb turned off (ie. dry), thus providing a blend of wet and dry instrumental mixes within the same file. Consult the Beatnik Editor for Macintosh's documentation for more information.

The standard General MIDI bank's percussion instruments (ie. Channel 10) already has dry/web instruments preset and is not affected by setReverbType. To create your own reverbed mix of percussion sounds, copy them into the user bank and reconfigure. The reverb types in the Beatnik Xtra are a subset of more specialised digital effects only available in the Xtra Pro, including higher quality reverbs and contemporary electronica effects. The replicated reverb type numbers are to maintain basic compatibility with RMF files composed for delivery via internet using the Beatnik Player's six different reverbs.

ReverbType Description
1
Bypass mode - ie. dry/no reverb
2
Acoustic Lab
3
Acoustic Lab
4
Acoustic Lab
5
Dungeon
6
Dungeon Reverb


Sample Code:

-- all musicObject instances will change to no reverb
on noReverb
setReverbType(beatnik,1)
end noReverb

-- all musicObject instances will change to acoustic lab
on midReverb
setReverbType(beatnik,2)
end midReverb


--------------------------------------------------------------------------------

setTempo

Syntax: setTempo(objectMe, integerTempoBeatsBerMinute)
Example: setTempo(beatnik, 120)
Related: getTempo


For the targetted musicObject instance, sets the tempo (playback speed) of the targeted file to a new absolute value. The new value is not calculated from the current playing tempo. ie. setTempo(beatnik, 50) = 50 beats per minute, setTempo(beatnik, 160) = 160 beats per minute. Each RMF or MIDI file has an individual tempo setting. Valid tempo range is from 0 to 300.

In order to affect the tempo in a way which relates to the current tempo, you should use getTempo to poll the current playing tempo, use Lingo to modify that value (eg. add/subtract or multiply it by a factor), and then call setTempo with that new modified value.

Note:

Can only be used while a song is playing and has no effect if a song is stopped. Playing automatically resets any tempo which was set while a song was stopped to the song's internal tempo setting.

Only supported for RMF (.rmf) files and MIDI (.mid) files. setTempo has no meaning for wav, aiff, au or mod samples. To playback supported samples at faster or slower speeds (similar to speeding up or slowing down a tape recorder), you must convert them into a user instrument in a RMF format file. This has the side advantage of being able to simultaneously playback multiple notes at different pitches/speeds based on the same sample, as well as providing reverb, better file compression settings and encrypted watermarking. Consult the Beatnik Editor for Macintosh for tutorials on this topic.

Sample Code:

-- where tempovalue is from 0 to 100
on tempoSlider tempovalue
set beatnikTempo = tempovalue * 3
setTempo(beatnik,beatnikTempo)
end tempoSlider


--------------------------------------------------------------------------------

setTrackMute

Syntax: setTrackMute(objectMe, integerTrackNumber, booleanMuteState)
Example: setTrackMute(beatnik, 62, TRUE)
Related: setChannelMute, getChannelMute, setChannelSolo, getChannelSolo, getTrackMute, setTrackSolo, getTrackSolo


For RMF or MIDI songs, Beatnik will handle playback of up to 64 discrete channels. setTrackMute mutes or unmutes the specified track based upon the boolean value used in the method. Using TRUE will mute a track and using FALSE will unmute a track. A track's current mute status can be obtained by using the getTrackMute method.

Note:

setTrackMute is not suitable for long sustained samples within tracks. Use setController(objectMe, integerMIDIChannelNum, 7, 1 or 127) to toggle sustained samples on and off instead. This however will have the restriction of affecting all tracks using that MIDI channel, as opposed to discrete control over 64 RMF or MIDI tracks.

Only supported for RMF (.rmf) files and MIDI (.mid) files. For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation.

Sample Code:

-- Various submixes of bass lines are in tracks 30-39.
-- This handler will successively advance through
-- the various bass line options available in song.

global currentBassTrk

on getNextBassLine
repeat with i = 30 to 39
setTrackMute(mySong,i,TRUE) -- mute all bass trks off first
end repeat
set currentBassTrk = currentBassTrk + 1
setTrackMute(mySong,currentBassTrk,FALSE) -- unmute new bass track
end getNextBassLine


--------------------------------------------------------------------------------

setTrackSolo

Syntax: setTrackSolo(objectMe, integerTrackNum, booleanSoloState)
Example: setTrackSolo(beatnik,54, TRUE)
Related: setChannelMute, getChannelMute, setChannelSolo, getChannelSolo, getTrackMute, setTrackMute, getTrackSolo


Sets the solo status of the specified track based upon the boolean value used in the method. Using true will solo a track and using false will unsolo a track. A track's current solo status can be obtained by using the getTrackSolo method.

Notes:

For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation. A non-standard MIDI implementation allows you to specify channel 0 (zero), which will alter all channels simultaneously.

Only supported for RMF (.rmf) files and MIDI (.mid) files. To use wav, aiff, au or mod samples, you must convert them into RMF format. Consult the Beatnik Editor for Macintosh and Beatnik Convertor for Windows for tutorials on this topic.

-- africanPercussion instance is RMF file with different African
-- percussion tracks on MIDI tracks 20-40.
-- on mouse click, we change to the next regional percussion instrument.
global regionalChannel

on mouseUp
set regionalChannel = regionalChannel + 1
if regionalChannel > 41 then set regionalChannel = 20
setTrackSolo(africanPercussion,regionalChannel,TRUE)
end mouseUp


--------------------------------------------------------------------------------

setTranspose

Syntax: setTranspose(objectMe, integerMusicalSemitoneIntervals)
Example: setTranspose(jazzPlayAlongSong, 1)
Related: getTranspose


Sets the pitch transposition value in semitone intervals of only the targeted file (musical intervals are often also referred to as half notes or semitones). integerMusicalSemitoneIntervals is an absolute value and setting it to equal zero (0) will reset transposition to the original key of the file. Continually changing integerMusicalSemitoneIntervals has no cumulative effect.

For example, if you setTranspose(objectMe,12), the file will transpose up by a complete octave but, if you issue that instruction again, the file simply remains at the current transposition. If you setTranspose(objectMe,0) the file will return to playing the default pitch of the file's initial loaded state.

Note:

Only supported for RMF (.rmf) files and MIDI (.mid) files. To playback supported samples files at higher or lower pitches (similar to speeding up or slowing down a tape recorder), you must convert them into a user instrument in a RMF format file. This has the side advantage of being able to simultaneously playback multiple notes at different pitches based on the same sample, as well as providing reverb, better file compression settings and encrypted watermarking. Consult the Beatnik Editor for Macintosh and Beatnik Convertor for Windows for tutorials on this topic.

Sample Code:

-- jazzPlayAlongSong instance can be transposed at will
-- to enable students to practise soloing in different keys
-- following button script shifts key up one semitone

global currentKey

on mouseUp
set currentKey = currentKey + 1
-- this handler resets octave transposition
-- to original pitch ie. no transposition
if currentKey > 11 then set currentKey = 0
setTranspose(jazzPlayAlongSong,currentKey)
end mouseUp


--------------------------------------------------------------------------------

setVolume

Syntax: setVolume(objectMe, integerVolumeLevel)
Example: setVolume(beatnik,100)
Related: getVolume, setController, getController


Sets the overall playback volume for the targeted musicObject instance. This is different to setting the individual volumes for MIDI channels in a music file, which can be done using MIDI Controller Change 7 with the setController method. Each music object instance has its own volume setting.

Sample Code:

on initVolume
-- initialize volume settings for all music and SFX
setVolume(popJingle,40)
setVolume(narration,70)
setVolume(GUIsounds,55)
end initVolume

Obtaining Playback State Information

Comprehensive playback properties can be obtained via these methods. These properties are generally set with their companion methods in the Realtime Control of Files and Song Control and Player Properties sections. By obtaining the current playback status of various song properties, one may make decisions to for your movie. eg. if the song is stopped, load the next song or display a message; if the song volume is set below a threshold, alter the color scheme of the user interface; poll getController for certain conditions of embedded MIDI Control Change information and execute handlers based on embedded MIDI information over time.

All of the methods listed below return values that indicate state information about the targeted Beatnik Player. They may be used in assignment statements, conditional statements, or expressions. The type of the value returned by each method (ie. string, integer, or boolean) is specified in the description for each method.




--------------------------------------------------------------------------------

isPaused

Syntax: isPaused(objectMe)
Example: set pauseState = isPaused(beatnik)
Related: isPlaying


Returns boolean TRUE if a file is currently in a paused state or FALSE if a file is in a play or stopped state. By testing isPaused, you may build your own GUI song transport controls, or jump to a different frame, open a Movie-In-A-window or any number of applications.

Sample Code:

-- for a kiosk application, if the narration
-- voice over is paused, turn on help screen
-- so user may select narration in other languages

on checkNarrationPaused
if (isPaused(kioskVoiceOver)) then
selectOtherLanguageOptions
end if
end checkNarrationPaused


--------------------------------------------------------------------------------

isPlaying

Syntax: isPlaying(objectMe)
Example: set atmosNotPlaying = isPlaying(atmosphere)
Related: isPaused


Returns boolean TRUE if a file is currently playing or FALSE if a file is in a paused or stopped state. See also the isPaused method. By testing isPlaying in conjunction with isPaused, you may tell if a file has been stopped or paused. As an example, a jukebox application can load a new song on a playlist, as the musicObject will automatically stop once a playing file has reached the last song position.

Sample Code:

-- for a jukebox application, if the current song
-- has stopped, then retrieve the next song title from
-- the playlist, and start playing automatically.
-- this handler would be polled periodically,
-- either by a timer or on exitFrame as examples.

on checkForNextSong, playListIndex
set playList = ["techno.rmf","classical.rmf","ambient.rmf","house.rmf"]
if (not(isPlaying(currentSong) and not(isPaused(currentSong)) then
set songTitle = getAt(playList,playListIndex)
setAutoStart(currentSong, TRUE)
play(currentSong)
end if
end checkForNextSong


--------------------------------------------------------------------------------

getChannelMute

Syntax: getChannelMute(objectMe, integerMIDIChannelNum)
Example: getChannelMute(beatnik, 10)
Related: setChannelSolo, getChannelSolo, getTrackMute, setTrackMute, setTrackSolo, getTrackSolo


Returns the current mute status of the specified MIDI channel. A value of true indicates that the channel is muted, and a value of false indicates that it is not muted. A channel's mute status can be set using the setChannelMute method.

Note:

Returns a boolean in the range of {true or false}. For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation. Only supported for RMF (.rmf) files and MIDI (.mid) files

Sample Code:

-- for a typical Enhanced CD remixer, check which
-- channel has been muted by user and return
-- status for further 'music-video' animations
-- triggered by channel mutes.
on init
global channelList
set channelList = [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
end init

on checkWhichChannelsMuted
global channelList
repeat with i = 1 to 16
if (getChannelMute(enhancedCDRemixer,i)) then
setAt(channelList,i,TRUE)
end if
end repeat
return channelList
end checkWhichChannelsMuted


--------------------------------------------------------------------------------

getChannelSolo

Syntax: getChannelSolo(objectMe, integerMIDIChannelNum)
Example: getChannelSolo(beatnik, 6)
Related: setChannelMute, getChannelMute, getChannelSolo, getTrackMute, setTrackMute, setTrackSolo, getTrackSolo


Returns the current solo status of the specified MIDI channel. A value of true indicates that the channel is soloed, and a value of false indicates that it is not soloed. A channel's solo status can be set using the setChannelMute method.

Note:

Returns a boolean in the range of {true or false}. For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation. Only supported for RMF (.rmf) files and MIDI (.mid) files.

Sample Code:

-- In a music courseware application, check which
-- channel is soloed and trigger highlights for
-- the particular channel's instruments on a
-- notated music staff.

on checkWhichChannelsSoloed
repeat with i = 1 to 16
if (getChannelSolo(orchestra,i)) then
highlightInstrument i
end if
end repeat
end checkWhichChannelsSoloed


--------------------------------------------------------------------------------

getController

Syntax: getController(objectMe, integerMIDIChannelNum, integerControllerNum)
Example: getController(animationMasterSync)
Related: setController


Gets the value of the specified MIDI controller on the specified MIDI channel. See the setController method for the full range of MIDI Controller Changes supported by the Beatnik Xtra.

Note:

Returns a value in the range of {0-127}. Only supported for RMF (.rmf) files and MIDI (.mid) files

Sample Code:

-- retrieve modulation wheel settings in dummy track to
-- control animation locV height synced to music track
on modWheeltoLocV
set spriteLocV = getController(animationSyncMaster,1,1)
return spriteLocV
end modWheeltoLocV
Or:
-- retrieve modulation wheel settings in dummy track to
-- synchronise ShockWave Flash frames to music track
on modWheeltoFlashFrame
set flashFrame = getController(animationSyncMaster,16,1)
set the frame of sprite 15 to flashFrame
end modWheeltoFlashFrame


--------------------------------------------------------------------------------

getLoop

Syntax: getLoop(objectMe)
Example: getLoop(beatnik)
Related: setLoop


Gets the current loop status of the musicObject instance (TRUE or FALSE). The loop status can be set with the setLoop method, play or playGroovoid methods.

Sample Code:

-- Check if song has been looped by user settings
on checkLoop
set x = getLoop(karaokeSong)
return x
end checkLoop


--------------------------------------------------------------------------------

getProgram

Syntax: getProgram(objectMe, integerMIDIChannelNum)
Example: getProgram(beatnik,3)
Related: setProgram
Returns the program number that is currently selected for the specified MIDI channel. This can be set using setProgram or program change events in the RMF or MIDI file.

Note:

Returns a value in the range of {0-127}. Only supported for RMF (.rmf) files and MIDI (.mid) files

Sample Code:

-- display current program that user has selected for
-- onscreen synth keyboard
on getTimbre
set i = getProgram(synth,1)
set timbreName = getAt(timbreList,i)
put timbreName into member timbreField
end getTimbre


--------------------------------------------------------------------------------

getReverbType

Syntax: getReverb(objectMe)
Example: getReverb(ambience)
Related: setReverbType


Gets the current reverb type as set by the setReverbType method.

Note:

Returns a value in the range of {0-6} [Temporary: Still to be finalised for Beatnik Xtra Lite.]

Sample Code:

-- check reverb and display reverb name
on checkReverb
set i = getReverbType(raveSong)
set j = getAt(reverbList,i)
put j into member reverbNameField
end checkReverb


--------------------------------------------------------------------------------

getTempo

Syntax: getTempo(objectMe)
Example: getTempo(beatnik)
Related: setTempo


Gets the current playing tempo value (measured in beats per minute) as set by the setTempo method and file's initial playing tempo.

Note:

Returns a value in bpm (beats per minute)
only supported for RMF (.rmf) files and MIDI (.mid) files

Sample Code:

-- increase tempo by 10 bpm
on bumpUpTempo
set i = getTempo(mySong) + 10
setTempo(mySong,i)
end bumpUpTempo


--------------------------------------------------------------------------------

getTrackMute

Syntax: getTrackMute(objectMe, integerTrackNum)
Example: getTrackMute(beatnik)
Related: setChannelMute, getChannelMute, setChannelSolo, getChannelSolo, setTrackMute, setTrackSolo, getTrackSolo


Returns the current mute status of the specified track. A value of true indicates that the track is muted, and a value of false indicates that it is not muted. A track's mute status can be set using the setTrackMute method.

Note:

Returns a boolean in the range of {true or false}. For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation. Only supported for RMF (.rmf) files and MIDI (.mid) files

Sample Code:

-- if drum track is muted then turn off drum icon sprite
if (getTrackMute(jazzBand,24)) then
set the visible of sprite drumIcon to 0
end if


--------------------------------------------------------------------------------

getTrackSolo

Syntax: getTrackSolo(objectMe, integerTrackNumber)
Example: getTrackSolo(beatnik, 64)
Related: setChannelMute, getChannelMute, setChannelSolo, getChannelSolo, getTrackMute, setTrackMute, setTrackSolo


Returns the current solo status of the specified track. A total of 64 tracks can be supported in any RMF or MIDI file. A value of true indicates that the track is soloed, and a value of false indicates that it is not soloed. A track's solo status can be set using the setTrackSolo method.

Note:

Returns a boolean in the range of {true or false}
For a more comprehesive explanation of mute and solo and how they interact with each other, consult the Mute and Solo documentation.
only supported for RMF (.rmf) files and MIDI (.mid) files

Sample Code:

-- check if current track is soloed
on checkSolo thisTrack
set i = getTrackSolo(salsaGroove,thisTrack)
return i
end checkSolo


--------------------------------------------------------------------------------

getTranspose

Syntax: getTranpose(objectMe)
Example: getTranpose(bluesExercise1)
Related: setTranspose


Gets the current tranposition value for the targeted file as set by the setTranspose method.

Note:

Returns a value in musical intervals
only supported for RMF (.rmf) files and MIDI (.mid) files

Sample Code:

-- displays tranposition interval of current song,
-- handler translates only for major and minor intervals
-- and does not account for augmented intervals.

on displayTranposition
global blueExercise1
set i = getTranspose(blueExercise1)
set j = ["minor 2nd","major 2nd","minor 3rd","major 3rd",
"perfect 4th", "diminished 5th","minor 6th",
"major 6th","minor 7th","major 7th","octave"]
if (i<0) then
set dir = "downwards"
set i = i * -1
else
set dir = "upwards"
end if

if (i=0) then
set k = "at tonic pitch"
set dir = ""
else
set k = getAt(j,i) && dir
end if
put k into member tranpositionField
end displayTranposition


--------------------------------------------------------------------------------

getVolume

Syntax: getVolume(objectMe)
Example: getVolume(raveParty)
Related: setVolume


Returns the current overall playback volume as set by setVolume, or the song when first initialized. Valid parameters are from 0 to 100.

Sample Code:

-- set volume to 10% lower of current volume
on lowerTenPercentVol
set i = getVolume(mySong)
set i = i - (i/10)
setVolume(mySong,i)
end lowerTenPercentVol


--------------------------------------------------------------------------------



©Copyright 1998 by Headspace, Inc. All rights reserved.

End of Document.