Beatnik Director Xtra musicObject Lingo Handlers Reference |
Beatnik Director Xtra - musicObject Lingo Handler Reference Version 1.02 |
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:
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.
|
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
Syntax: | set globalVariable = new(xtra "beatnik", booleanDTCorMOA) |
Example: | set myBeatnikBand = new(xtra "beatnik", false) |
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
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)
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
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)
Syntax: | setPreferredSoundChannel(objectMe, integerSliceSize) |
Example: | setPreferredSoundChannel (beatnik,12) |
Syntax: | setReady(objectMe) |
Example: | setReady(beatnik) |
Related: | isReady, closeBeatnik |
Initialize Beatnik Engine.
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.
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
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 |
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
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
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
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
Syntax: | getVersion(objectMe) |
Example: | getVersion(beatnik) |
Sample Code:
on checkXtraVersion global beatnik alert getVersion(beatnik) end checkXtraVersion
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
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
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?
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.
|
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
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
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
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.
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
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
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.
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
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
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
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)
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
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
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
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
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
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 |
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.
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
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
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
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
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
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
Syntax: | getProgram(objectMe, integerMIDIChannelNum) |
Example: | getProgram(beatnik,3) |
Related: | setProgram |
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
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
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
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
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
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
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.