extra/audio/loader/loader-docs.factor

   1 ! Copyright (C) 2010 Joe Groff.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: audio help.markup help.syntax kernel quotations strings ;
   4 IN: audio.loader
   5
   6 HELP: read-audio
   7 { $values
   8     { "path" "a pathname string" }
   9     { "audio" audio }
  10 }
  11 { $description "Reads the audio data from the file on disk named " { $snippet "path" } ", saving the data in an " { $link audio } " object. If the file's extension is not recognized, an " { $link unknown-audio-extension } " error is thrown." } ;
  12
  13 HELP: register-audio-extension
  14 { $values
  15     { "extension" string } { "quot" quotation }
  16 }
  17 { $description "Registers a quotation for " { $link read-audio } " to use when reading audio files with filenames ending in " { $snippet ".extension" } ". The quotation should have the effect " { $snippet "( path -- audio )" } ", where " { $snippet "path" } " is the file's pathname and " { $snippet "audio" } " is the resulting " { $link audio } " object." } ;
  18
  19 HELP: unknown-audio-extension
  20 { $values
  21     { "extension" string }
  22 }
  23 { $description "Errors of this class are thrown by " { $link read-audio } " when it cannot recognize the extension of the file it is given to open." } ;
  24
  25 ARTICLE: "audio.loader" "Audio file loader"
  26 "The " { $vocab-link "audio.loader" } " vocabulary provides words for reading uncompressed PCM data from files on disk."
  27 { $subsections
  28     read-audio
  29 }
  30 "Other vocabularies can extend " { $link read-audio } " by adding support for other audio file formats."
  31 { $subsections
  32     register-audio-extension
  33     unknown-audio-extension
  34 }
  35 "By default, " { $snippet "audio.loader" } " supports WAV (with the file extension " { $snippet ".wav" } ") and AIFF (with extension " { $snippet ".aif" } " or " { $snippet ".aiff" } ")." ;
  36
  37 ABOUT: "audio.loader"