Enhanced Music Library v1.7 For Blitz Basic 2 (C) Paul Reece 1996 Official Library Number: 60 DISCLAIMER: ----------- This is BETA RELEASE software. The author takes no responsibility for any damages, loss of data etc. caused whilst using this program. The user accepts all responsibility upon loading this software ie. USE AT YOUR OWN RISK! The author, however will attempt to eradicate all known bugs when they are reported. USERS PLEASE NOTE: ------------------ The libraries are currently numbers 60, 11 and 12. This release only contains the first library of the set of 3 - The other libs will be released in the near future... -- Tracker Commands -- (These commands are contained in EMLLIB.OBJ) Command: LoadPTModule --------------------- Syntax: LoadPTModule PTModule#,Filename$ suc.b=LoadPTModule(PTModule#,Filename$) Modes: Amiga Description: This command loads the specified file into the specified ptmodule object. If used as a function, it returns TRUE (-1) if there were no errors. Command: SavePTModule --------------------- Syntax: SavePTModule PTModule#,Filename$ suc.b=LoadPTModule(PTModule#,Filename$) Modes: Amiga Description: This command saves the specified ptmodule object into the file specified. If use as a function, it returns TRUE (-1) if there were no errors. Statement: PlayPTModule ----------------------- Syntax: PlayPTModule PTModule#[,Position] Modes: Amiga/Blitz Description: Play a module loaded in as the specified Blitz ptmodule object. The optional position parameter allows you to specify a starting position to play from. Modules will play correctly in BLITZ mode in version 1.90 and higher of Blitz Basic 2. For playing on other versions of Blitz2 in BLITZ mode, see the details for SetPTNoInt below. Statement: StopPTModule ----------------------- Syntax: StopPTModule Modes: Amiga/Blitz Description: Stops any ptmodule that may be playing. Statement: PausePTModule ------------------------ Syntax: PausePTModule Modes: Amiga/Blitz Description: Pauses any playing ptmodule. Statement: ContPTModule ----------------------- Syntax: ContPTModule Modes: Amiga/Blitz Description: Continues any paused ptmodule from the point it was paused at. Statement: SetPTSongLoop ------------------------ Syntax: SetPTSongLoop On|Off Modes: Amiga/Blitz Description: This command determines whether a tracker module repeats from the start when a module ends. As a default, any module will stop when the end is reached. Statement: SetPTPatLoop ----------------------- Syntax: SetPTPatLoop On|Off|Once Modes: Amiga/Blitz Description: This command turns on the pattern looping features of the playroutine. The On option will cause the current (or next if music has not started) pattern to repeat until the music is stopped. The Off option is the default, which causes music to play as normal. The Once option causes the current (or next if music has not started) pattern to play once and then the music will stop automatically. Statement: SetPTZeroSpeed (previously SetPTZeroTempo) ------------------------- Syntax: SetPTZeroSpeed On|Off Modes: Amiga/Blitz Description: This command tells the playroutine to either stop when a tempo set 0 command is encountered, or to keep playing. The On option allows you to set tempo 0 without the music stopping. The default is to stop the ptmodule. Statement: SetPTVolume ---------------------- Syntax: SetPTVolume Volume Modes: Amiga/Blitz Description: Sets the master volume of any playing or to-be-played ptmodule. The volume value must be between 0 and 64. The setting is copied to ALL voices. Statement: SetPTVoiceVolume --------------------------- Syntax: SetPTVoiceVolume Voice,Volume Modes: Amiga/Blitz Description: Sets the master volume of the specified voice. Function: GetPTVoiceVolume -------------------------- Syntax: vol.b=GetPTVoiceVolume(Voice) Modes: Amiga/Blitz Description: Returns the master volume of the voice specified. Statement: SetPTSpeed --------------------- Syntax: SetPTSpeed Speed Modes: Amiga/Blitz Description: This command sets the speed of the currently playing ptmodule. The value must be between 0 and 32 - The default is 6. Function: GetPTSpeed -------------------- Syntax: speed.b=GetPTSpeed Modes: Amiga/Blitz Description: This function returns the current speed setting. Statement: SetPTTempo --------------------- Syntax: SetPTTempo CiaTempo Modes: Amiga Description: This command sets the CIA tempo of the currently playing module. This will only work when the CIA playroutines are being used. Valid values are from 33 to 255. The default value is 125. Function: GetPTTempo -------------------- Syntax: tempo.w=GetPTTempo Modes: Amiga Description: This function returns the current tempo setting. Statement: SetPTMask -------------------- Syntax: SetPTMask Voices This command toggles on/off the music playing on the specified voices. This allows you to mask out channels for the playing of samples only etc. The bitmap specifies which voices are on and off - Just set/not-set the bit(s) relating to the channels. eg. %0001 - Channel 0 ON ONLY! %1011 - Channel 2 OFF ONLY! %1000 - Channel 3 ON ONLY! Function: GetPTMask ------------------- Syntax: mask.b=GetPTMask Modes: Amiga/Blitz Description: This function returns the current protracker mask. Statement: SetPTVoiceOff ------------------------ Syntax: SetPTVoiceOff Voice Modes: Amiga/Blitz Description: Turns the specified voice off - No protracker music will be played on the specified voice. Statement: SetPTVoiceOn ----------------------- Syntax: SetPTVoiceOn Voice Modes: Amiga/Blitz Description: Turns the specified voice on - Allows protracker music to be played on the specified voice. Statement: SetPTVoiceToggle --------------------------- Syntax: SetPTVoiceToggle Voice Modes: Amiga/Blitz Description: Toggles the specified voice from off to on or on to off... Function: GetPTVoiceStat ------------------------ Syntax: stat.b=GetPTVoiceStat(Voice) Modes: Amiga/Blitz Description: This function returns true (-1) if the voice specified is turned on, or false (0) if it is turned off. Function: GetPTVoicePeriod -------------------------- Syntax: period.w=GetPTVoicePeriod(Voice) Modes: Amiga/Blitz Description: This function returns the sample-period value of the last, or current note played on the specified channel. Function: GetPTVoiceNote ------------------------ Syntax: note.b=GetPTVoiceNote(Voice) Modes: Amiga/Blitz Description: This function returns the note number of the last, or current note played on the specified channel. Function: GetPTVoiceInstrument ------------------------------ Syntax: instrument.b=GetPTVoiceInstrument(Voice) Modes: Amiga/Blitz Description: This function returns the instrument number of the last, or current note played on the specified channel. Function: GetPTVuLevel ---------------------- Syntax: vu.b=GetPTVuLevel(Voice) Modes: Amiga/Blitz Description: This functions returns the 'original' volume level of the last note played on the specified channel. Function: GetPTRealVuLevel -------------------------- Syntax: vu.b=GetPTRealVuLevel(Voice) Modes: Amiga/Blitz Description: This functions returns the volume level of the last/current note on the specified channel. Function: GetPTSongPos ---------------------- Syntax: pos.b=GetPTSongPos Modes: Amiga/Blitz Description: This function returns the current position of the ptmodule currently playing. Function: GetPTPatternPos ------------------------- Syntax: pos.b=GetPTPatternPos Modes: Amiga/Blitz Description: This function returns the current position of the currently playing pattern. (ie. the line number on tracker programs) Function: GetPTStat ------------------- Syntax: stat.b=GetPTStat Modes: Amiga/Blitz Description: This function returns the object number of any ptmodule currently playing OR -1 if no ptmodule is playing. -- PTModule Information -- Function: GetPTModuleLen ------------------------ Syntax: len.l=GetPTModuleLen(PTModule#) Modes: Amiga/Blitz Description: This function returns the length (in positions) of the ptmodule specified. Function: GetPTPosPattern ------------------------- Syntax: pat.b=GetPTPosPattern(PTModule#,Position) Modes: Amiga/Blitz Description: This function returns the pattern number that is played at the specified position in the specified ptmodule. Function: GetPTModuleName$ -------------------------- Syntax: name$=GetPTModuleName$(PTModule#) Modes: Amiga/Blitz Description: This function returns the name of the specified ptmodule. Function: GetPTInstrumentName$ ------------------------------ Syntax: name$=GetPTInstrumentName$(PTModule#,InstrumentNumber) Modes: Amiga/Blitz Description: This function returns the name of the specified instrument. Function: GetPTInstrumentAddr ----------------------------- Syntax: addr.l=GetPTInstrumentAddr(PTModule#,InstrumentNumber) Modes: Amiga/Blitz Description: This function returns the start address of the specified instrument. Function: GetPTInstrumentLen ---------------------------- Syntax: len.l=GetPTInstrumentLen(PTModule#,InstrumentNumber) Modes: Amiga/Blitz Description: This function returns the length of the specified instrument. Function: GetPTInstrumentRepeatStart ------------------------------------ Syntax: rep.l=GetPTInstrumentRepeatStart(PTModule#,InstrumentNumber) Modes: Amiga/Blitz Description: This function returns the offset from the start of the sample, where the looping of the sample starts. Function: GetInstrumentRepLen ----------------------------- Syntax: replen.l=GetPTInstrumentRepLen(PTModule#,InstrumentNumber) Modes: Amiga/Blitz Description: This function returns the offset from the start of the sample, where the looping of the sample ends. Function: GetPTInstrumentVol ---------------------------- Syntax: vol.b=GetPTInstrumentVol(PTModule#,InstrumentNumber) Modes: Amiga/Blitz Description: This function returns the volume setting for the specified instrument. -- Advanced Tracker Commands -- Statement: SetPTCia ------------------- Syntax: SetPTCia Modes: Amiga/Blitz Description: This command tells the playroutine to use CIA interrupts (and thus CIA tempos) when playing ptmodules. It will not switch interrupts whilst playing - if you do so, any currently playing ptmodules will stop. Statement: SetPTVbl ------------------- Syntax: SetPTVbl Modes: Amiga/Blitz Description: This command tells the playroutine to use VBL interrupts (and thus VBL tempos) when playing ptmodules. Statement: SetPTNoInt --------------------- Syntax: SetPTNoInt Modes: Amiga/Blitz Description: This command tells the library not to start an interrupt when playing a song. It is left to the use to use the PTInt statement each VBL to play the music. Note! This method only allows VBL tempos, but it DOES allow you to play music in Blitz mode on older versions of Blitz! Statement: SetPTCiaInt ---------------------- Syntax: SetPTCiaInt Type Modes: Amiga/Blitz Description: This command tells the playroutine to utilize the specified interrupt type (like what is specified in the SetInt command) to use when using CIA's. Statement: SetPTCiaPri ---------------------- Syntax: SetCiaPri Priority Modes: Amiga/Blitz Description: This command sets the internal priority of the CIA interrupt. BE CAREFULL!! You can un-intentionally cripple your disk interrupts by using a value too high!! Statement: PTInt ---------------- Syntax: PTInt Modes: Amiga/Blitz Description: Called once every VBL (when in NoInt mode), this statement will play the previously started ptmodule. -- Sample Commands -- (These routines are contained in EMLLIB2.OBJ) (NOT included in this release!) Statement: Sample ----------------- Syntax: Sample StartAddress,Length,Frequency Modes: Amiga/Blitz Description: This command takes a sample using any connected sampler cartridge.. The sampling speed is measured in hertz and must be higher than 500!! Sampling will stop when the length is reached or any mouse button is pressed. Whilst sampling, ALL interrupts and the Screen DMA are de-activated. NB: Samplers connected to the BUS port will NOT work. (ala DATEL) Statement: SampleSound ---------------------- Syntax: SampleSound Sound#,Frequency Modes: Amiga/Blitz Description: This command takes a sample but samples into the specified sound object. Sampling will stop when the length of the sound is reached or any mouse button is pressed. NOTE!: Frequency must be higher than 500! Statement: Monitor ------------------ Syntax: Monitor Frequency Modes: Amiga/Blitz Description: This command monitors the input of the sampler and outputs it through the Amiga's sound channels. Any mouse button stops monitoring. Whilst monitoring, ALL interrupts are disabled. NOTE!: Frequency must be higher than 500! Function: Period ---------------- Syntax: Period(Hertz) Modes: Amiga/Blitz Description: This function converts a value in hertz to an Amiga sample period. Function: Hertz --------------- Syntax: Hertz(Period) Modes: Amiga/Blitz Description: This function converts an Amiga sample period to a value in hertz. Copyright, Contact Information, Disclaimer etc..: ------------------------------------------------- This program is NOT Public Domain, FreeWare, etc.. The author retains FULL copyright of the program, examples and documentation. This program is NOT to be sold by ANY PD library without written agreement with myself.. It may NOT be uploaded to ANY ftp site or BBS either. Updates will be released by the author on aminet as required. Placement of this program on ANY CD-Rom will ALSO be seen as a breach of these conditions. Also, ANY use of this program in a shareware/commercial software release must be agreed-to by myself IN WRITING before any such release. (usually all I'll want is a free copy of the game/program ;) ) For more information in this regard, or for making suggestions/reporting bugs, please contact me! (Please mail bugs in the manual to me too!! It was done in a hurry!) Postal: Paul Reece 12 Howe Elbow, Quinns Rocks, Western Australia. 6030. (only til mid 1996 at this stage) Internet: paul@tassie.net.au, st962f8e@echidna.cowan.edu.au Also Available: THE ENHANCED MUSIC EXTENSION for AMOS 1.3 / AMOS PRO. BTW: If anyone is interested in saving me the time of converting this into a nice looking .guide, let me know :-) PROGRAM HISTORY: ---------------- v1.7 (19-APR-1996) - Totally replaced and rewrote playroutine - now uses busywait fixed routine by Peter Kunath (hi Deli!). Code generally cleaned up at the same time.. Bugs most likely introduced here :) v1.6 (??-MAR-1996) - Many attempts to fix a damned playroutine bug. Still dropping notes :( v1.55 (11-NOV-1995) - Gee! I only just decided to look at this today.. Fixed problem with CIA allocation - munged the serial port. v1.54 (24-SEP-1994) - Code cleaned up even more - Portamento problem fixed (bug in Protracker Playroutines - not in PT itself though....) v1.53 (16-SEP-1994) - Return values for LOAD and SAVE added - First public release. v1.52 (15-SEP-1994) - GetPTVoiceNote added. GetPTRealLevel added. Code cleaned up. v1.51 (8-SEP-1994) - SavePTModule fixed. Some code cleaned up. v1.5 (27-JUL-1994) - Tempo/Speed commands/functions fixed and extended. Master volume setting for voices now included. v1.4 (20-JUL-1994) - First release version.. Only 1 lib included (no. 60) New libnumber!! (60) Commandnames changed. Not int option added. Uses it's own Blitz objects! v1.3 (16-JUN-1994) - ALOT of bugs fixed here.. Too many to list! v1.2b(6-JUN-1994) - Now a third library.. Doesn't do much yet, but will soon have full TFMX playroutines... Work is still in progress. v1.2 (5-JUN-1994) - New sampling commands added! Program now consists of 2 libraries. v1.1 (1-JUN-1994) - CIA or VBL added. Instrument information functions added and interrupts finally fixed! v1.0 (30-MAY-1994) - First version - Only released to 1 person. Full of BUGS! Written from scratch in only 3 days! v0.0 (27-MAY-1994) - Blitz2 arrived in the mail TODAY.