home *** CD-ROM | disk | FTP | other *** search
/ Fujiology Archive / fujiology_archive_v1_0.iso / !FALCON / NOCREW / MP2_0997.ZIP / mp2_0997 / help.txt < prev    next >
Text File  |  1999-07-28  |  9KB  |  243 lines
  1. Since version 0.99, a number of changes were introduced in MP2Audio. 
  2.  
  3. So, what's new in this version? Well, just about everything with the
  4. interface, and nothing at all with the DSP player. The appearance of
  5. the GEM interface is very much the same as the last version. One
  6. button has been replaced, namely the count direction button which now
  7. contains a lambda symbol, to symbolize the integrated script language
  8. which now controls large parts of the player. The language is called
  9. Shoe, and is written by Fredrik Noring. It's contructed to be a small
  10. and easily extendable LISP like language. 
  11.  
  12. Large parts of the C code has been replaced by Shoe functions or
  13. combinations of Shoe functions. All buttons and control keys are
  14. controlled via Shoe. This means that you can map the control keys and 
  15. buttons to any function you like. It is not possible to change the
  16. icons on the buttons right now, but this might be implemented in a 
  17. later version.
  18.  
  19. The mp2audio.sho file has also replaced the configure file that was
  20. previously used. With this alpha version, not all configure functions 
  21. have been implemented in Shoe yet. You can't set which clock to use, 
  22. automatic detection will always be used. Time slice and buffer size
  23. is constant, unless you recompile the program, of course. If you ask
  24. me nicely, I might recompile a new version with the values you want, 
  25. if you're not happy with the current values. 
  26.  
  27. Right now, the program _needs_ the mp2audio.sho to be in the same 
  28. directory as the program file, or no mappings of the buttons and keys
  29. are made, and you can't do anything but to end the program. This will
  30. change later, and the basic functions will be mapped by the program
  31. itself. 
  32.  
  33. When you start the program, with the mp2audio.sho file included in this
  34. package, it will behave very much like the previous versions. By pressing
  35. control+j you will enter Jukebox mode. In this mode, when you load a song
  36. it is pushed into a play list, and by pressing the play button, it will
  37. play the first song on the list. Following presses on the load or play
  38. button will not stop the current song, but only push the new selected
  39. song onto the play list. To change to next song, press the next button. 
  40. This will start playing the first song in the play list, and remove it
  41. from the list at the same time. The previous button hasn't been mapped
  42. in Jukebox mode. 
  43.  
  44. I suggest that you read through the mp2audio.sho file and try to figure
  45. out as much as possible what it does. I'll try to list the most common
  46. Shoe functions here, but I'll probably miss some of them.
  47.  
  48. When you press the lambda button, a console window will pop up. This is
  49. a very simple line editor with a history list. When you enter expressions
  50. you can break lines at any place a normal space would have been inserted.
  51. Since LISP, and therefore also Shoe, contains a lot of parantheses, these
  52. might be difficult to keep track of. The console prints the number of
  53. unclosed parantheses as a number before the prompt. Expressions will be
  54. evaluated when the parantheses are in balance. 
  55.  
  56. Shoe uses lists for most thing. These are written as:
  57.   (element1 element2 element3)
  58. where the elements can be numbers, symbols or lists.
  59. Functions are used by writing a list with the function name as the first
  60. element and its arguments as the following ones. Exemple:
  61.   (+ 1 2 3)
  62.  
  63. Numbers are only integers. Symbols may not begin with a number.
  64. For the following examples, assume that "test" is a list containing
  65. three elements, a, b and c, like this:
  66.     > test
  67.     (a b c)
  68.  
  69. True and false values are represented as #t and #f respectively.
  70.  
  71. Values inside "" are quotes, which means the value should not be evaluated.
  72.  
  73. Shoe internal functions:
  74.  
  75. +    Add the arguments.
  76. -    Subract the arguments three and forward from the first.
  77. /    Divide the first argument with the arguments three- multiplicated
  78.     with each other.
  79. *    Multiply all arguments.
  80. %    Give the rest of a division, i.e. modulo.
  81.  
  82. car    Return the first element or a list.
  83.     > (car test)
  84.     a
  85.  
  86. cdr    Return the list that remains if the first element is removed.
  87.     > (cdr test)
  88.     (b c)
  89.  
  90. if    If expression is true, do the true-statement, otherwise do the
  91.     false-statement.
  92.     > (if expression true-statement false-statement)
  93.     [result of true- or false-statement]
  94.  
  95. cons    Put an element in the first position of a list.
  96.     > (cons "q" test)
  97.     (q a b c)
  98.  
  99. define    Define a new function. Functions can only do one expression now,
  100.     but with the "begin" statement, several can be used.
  101.     > (define fac (n)
  102.     1> (if (< n 1) 1
  103.     2>   (* n (fac (- n 1)))))
  104.     fac
  105.     
  106.     This means the function 'fac' has been defined and it takes one
  107.     argument, n. Use the function like this:
  108.     > (fac 5)
  109.     120
  110.     
  111. begin    Combine several statements, evaluate them all in order, and return
  112.     the value of the last one.
  113.     > (begin (fac 2) (fac 3))
  114.     6
  115.     
  116. equal    Returns #t if both arguments are equal and #f otherwise.
  117.  
  118. eval    Evaluate a statement.
  119.     > (eval test)
  120.     #ERR.
  121.     
  122.     Bad example, but it tries to use (a b c) as a function call, with
  123.     'a' being the function name and 'b' and 'c' as its arguments.
  124.  
  125. sort    Sort a list in alphabetical increasing order.
  126.     > (sort (cons "q" test))
  127.     (a b c q)
  128.     
  129.  
  130. MP2AUDIO specific functions:
  131.  
  132. pwd    Return the current directory in a list.
  133.     > (pwd)
  134.     d:\mp2\jarre\
  135.  
  136. cd    Change the current directory, relative, or absolute and return the
  137.     new directory.
  138.     > (cd "zoolook")
  139.     d:\mp2\jarre\zoolook
  140.  
  141. ls    Return the files in the current directory as a list. An argument
  142.     may be used to 'ls', and is the search mask, e.g. "*.mp?".
  143.     > (ls)
  144.     (. .. 02diva.mp2 01ethni.mp2)
  145.     > (ls "*.mp2")
  146.     (02diva.mp2 01ethni.mp2)
  147.  
  148.     'ls' does not sort the files in alphabetical order, but only list
  149.     them as they appear on the disk. To sort, use the 'sort' function:
  150.     > (sort (ls "*.mp2"))
  151.     (01ethni.mp2 02diva.mp2)
  152.  
  153. mp2-dsp-load   Returns the load of the DSP decoder. Two values are 
  154.                provided: current load and average load. 0 means
  155.                that the decoder is totally idle. 100 means that
  156.                the decoder is busy all the time, which is not a
  157.                very good thing.
  158.  
  159. mp2-external-clock?  Returns the external clock frequencies. It
  160.                      supports dual clocks with both 44.1 and 48KHz. 
  161.                      The returned value is a list of two values, 
  162.                      the frequencies of each clock respectively. If
  163.                      there isn't a dual clock available, it will 
  164.                      give the same fequencies for both values. If
  165.                      an external clock is not found, both values will
  166.                      be zero (0).
  167.                      
  168. mp2-external-clock   Set the clock frequencies. This is mainly for
  169.                      testing purposes, and in case the automatic
  170.                      clock detection would fail. The parameter should
  171.                      be a list with two values, corresponding to the
  172.                      values described in the above function. 
  173.  
  174. mp2-play        Play the loaded song, if any.
  175. mp2-stop        Stop the currently playing song.
  176. mp2-pause        Pause or unpause the current song.
  177. mp2-load        Load a song with the filename as argument.
  178. mp2-fast-forward    Fast forward the currently playing song.
  179. mp2-loop        Set loop or not loop the current song.
  180. mp2-window-info        Open the Info window.
  181. mp2-window-console    Open the Console window.
  182. mp2-select        Open a fileselector and return the choosen name
  183.             or #f if none was choosen.
  184.  
  185. mp2-countdown        Toggle counting direction of time. If argument #t
  186.             or #f are given, set the direction accordingly.
  187. mp2-display-time    Toggle (or set) if the time should be displayed
  188.             in the title of the main window.
  189. mp2-title        Set the title of the main window.
  190. mp2-subtitle        Set the subtitle of the main window. This is where
  191.             the song name of the current song is usually written.
  192.  
  193. mp2-type        Return a list of information about the loaded song.
  194. mp2-play-time        Return the amount of seconds that has been played.
  195.  
  196. The following are functions that is being called by the program
  197. if the respective button is being pressed down:
  198.  
  199. mp2-icon-play
  200. mp2-icon-stop
  201. mp2-icon-pause
  202. mp2-icon-load
  203. mp2-icon-next
  204. mp2-icon-previous
  205. mp2-icon-fast-forward
  206. mp2-icon-loop
  207. mp2-icon-info
  208. mp2-icon-console
  209.  
  210. control-key-?    Replace the '?' with any letter, a-z or A-Z, and that
  211.         function is called when control+? key is pressed. Capital
  212.         control-key functions are called when shift is also pressed.
  213.  
  214. mp2-hook-finitum    This function is called when the current song has
  215.             finished playing.
  216.  
  217. mp2-hook-loaditum    This function is called when a song has been loaded.
  218.             It is only called if the MPEG file is valid.
  219.  
  220. mp2-hook-dragumdroppum    This function is called when the user has either
  221.             entered a filename at the command line, dragged a
  222.             file to the program, or in MultiTOS dragged a file
  223.             to any of the windows belonging to the program.
  224.             Running Thing or another desktop that supports the
  225.             VA-protocol, this function is also called when a
  226.             filename is sent to the already started program.
  227.  
  228.  
  229. The following functions return #t or #f depending on states of the player:
  230.  
  231. mp2-play?
  232. mp2-pause?
  233. mp2-loaded?
  234. mp2-loop?
  235.  
  236.  
  237. The file mp2audio.sho contains some other common LISP functions, such as
  238. 'cond', 'list', 'assoc', 'member', boolean operations and more. Have a look
  239. at the file.
  240.  
  241.  
  242. Tomas Berndtsson <tomas@nocrew.org>
  243.