24U SimpleSound Plug-In 3.0 Syntax

This file describes syntax of 24U SimpleSound Plug-In's functions.
 

SSound_Version ( versionFormat )
 
Returns version string of the active 24U SimpleSound Plug-In, formatted as requested by the parameter. Use:

"short" to get just the version number
"long" to get the plug-in name followed by its version number
"platform" to get the platform of the code currently running
 

SSound_Register ( registrationCode )
 
Attempts to unlock (register) your copy of 24U SimpleSound Plug-In with the specified code. If the code is valid, 24U SimpleSound Plug-In gets unlocked and stays in this state until you quit the FileMaker application, deactivate the plug-in, or the registration code expires. While unlocked, 24U SimpleSound Plug-In is fully functional and does not bother the user with a shareware reminder.
 
Returns a non-zero result when operation is not permitted.
 

SSound_Playback( command{; soundspec{; offset}} )

This command controls playback of sounds. Two calling variants are possible.

    

SSound_Playback( startcommand ; soundspec{; offset} )

    startcommand
       "play synchronously" starts synchronous playback. The user has to wait until the playback is finished and cannot do anything else.
  "play" starts playing a sound in the background.
  "loop" starts playing a background sound in a loop again and again, until stoped by the "stop" command.
  "palindrome" starts "palindrome" looping a background sound until stoped by the "stop" command.
    soundspec
  identifier of the desired sound. See how the sound can be specified.
    offset
  (fractional) number of seconds from the beginning of the sound where the playback should start. Default is 0.
     
return value 0 or negative error number
 
    

SSound_Playback( controlcommand{; soundspec} )

    soundspec
  identifier of the sound which is to be controlled. If more instances of one sound are playing the control command is applied to all. If soundspec is not given, the control command is applied on all currently playing sounds. See how the sound can be specified.
    controlcommand
       "stop" stops playing of the given sound.
  "pause" pauses playing of the given sound. It can be later resumed by the "resume" command.
  "resume" resumes playing of the in given sound previously paused with the "pause" command.
     
return value 0 or negative error number

SSound_Recording( command {;filespec} {; filename} )

This command controls recording of sounds. Three calling variants are possible.

    

SSound_Recording( controlcommand)

    controlcommand
       "start" starts recording to a temporary storage in a system temporary directory.
  "cancel" cancels the current recording and discards the recorded sound.
  "pause" pauses the current recording. It can be resumed with the "resume" command later on.
  "resume" resumes the recording previusly paused with the "pause" command.
     
return value 0 or negative error number
 
    

SSound_Recording( "store"; filespec)
   stops the current recording and saves its result into desired file.

    soundspec
       identifier of the file where the result of recording should be stored. See how the sound can be specified. The resulting sound format is selected according to the extension of the desired file. The extensions "wav", "aiff" and "mov" are supported. For another extension, the type "mov" is used.
                    
return value 0 or negative error number
 
    

SSound_Recording( "store to container"; filename)
   stops the current recording and returns the result in form of binary data which can be directly placed into a container.

    filename
      filename assigned to the resulting container. The resulting soundformat is selected according to the extension of this filename. The extensions "wav", "aiff" and "mov" are supported. For another extension, the type "mov" is used.
                 
return value binary data or negative error number

SSound_Get( selector{ ; soundspec })
  This command can be used to retrieve usefull general and sound specific information. Three calling variants are possible.

    

SSound_Get( globalselector)
  Returns general information.

    globalselector
       "recording offset" (fractional) number of seconds, current length of the sound currently being recorded.
  "recording options" encoded recording options. Result is not human readable but can be stored and later passed to the SSound_Set("recording options";option) function to restore the current settings.
  "quicktime version" version of the QuickTime installed. e.g.: 7.1.2
  "number of playing sounds" number of sounds currently being played back including the paused sounds.
  "recording status" information about remaining storage cappacity. This command is available only when recording.
   
return value requested value or negative error number
 
    

SSound_Get( "playback offset"{; soundspec})
   Returns (fractional) number of seconds from the beginning of the specified sound.

    soundspec
       identifier of the sound to get playback offset of. Default is the most recently started sound.
   
return value requested value or negative error numberr
 
    

SSound_Get( localselector; soundspec)
  Returns information relevant to the specified sound.

    localselector
       "length as time" length of the file returned as time record. e.g: 0:00:05
  "length as seconds" length of the file returned as (fractional) number of the seconds. e.g :5.3311666
  "number of samples" e.g.: 231569
  "file format" four-char code of the file format as recognized by the QuickTime movie importer. e.g. "WAVE","Mp3 "
  "data format" format of the data. For uncompressed sounds it returns values like "Unsigned Integer" or "Integer (Little Endian)", for compressed sounds it returns human readable deascription of the compression, e.g.:"MPEG Layer 3"
  "sample size" sample size in bites. e.g.: 8
  "sampling rate" sampling rate in Hz. e.g.:11025
  "bit rate" human readable bitrate. e.g.: "88200 bps"
  "number of channels" e.g.:2
  "ID3 tagname" value of ID3 tag. tagname can be Track, Title, Artist, Album, Year, Genre or Comment
  "ID3 tagcode" value of ID3 tag specified by its code. tagcode can be any ID3 tag code, e.g: TOPE, TENC TOAL TOFN
    soundspec
       identifier of the sound to get info for.
   
return value requested value or negative error number
 
    

SSound_Set( selector{ ; value{; soundspec} })
  This command can be used to set usefull general and sound specific information. Three calling variants are possible.

    

SSound_Set( "recording options" { ; options })
  Sets the recording options.

    options
       binary encoded recording options (if not given, options dialog is displayed)
   
return value 0 or negative error number
 
    

SSound_Set( id3selector ; tagvalue; filespec)
   Sets value of ID3 tag to the sound stored in a file.

    id3selector
       "ID3 tagname" ID3 tag specified by name. tagname can be Track, Title, Artist, Album, Year, Genre or Comment
  "ID3 tagcode" ID3 tag specified by code. tagcode can be any ID3 tag code, e.g: TOPE, TENC TOAL TOFN
    tagvalue
       string with the value to set to the specified ID3 tag.
    filespec
       identifier of the sound file to set the value of ID3 tag to.
   
return value 0 or negative error number
 
    

SSound_Set( id3selector ; tagvalue; container)
   Sets value of ID3 tag to the sound stored in a container.

    id3selector
       "ID3 tagname" ID3 tag specified by name. tagname can be Track, Title, Artist, Album, Year, Genre or Comment
  "ID3 tagcode" ID3 tag specified by code. tagcode can be any ID3 tag code, e.g: TOPE, TENC TOAL TOFN
    tagvalue
       string with the value to set to the specified ID3 tag.
    container
       binary data passed from a container
   
return value binary data which should be put into a container or negative error number
 
    

Specifying a Sound

24u SimpleSound Plug-in can work with two type of sounds.

  1. sound residing on the HD, specified by filespec
  2. sound residing directly in the FM container

There are only small differences between working with file sounds and container sounds. If the function syntax refers to the sound as soundspec, it means that it works with both types of sounds. If there is a need to distinguish these types, the sounds are refered to as filespec or container respectively.

filespec is a text with file path ( absolute or relative to the currently opened FM document). These path specifications are accepted:

fsspec
"fsspec:volume_id:folder_id:file"
win-relative
" folder\another folder\file" (works on both platforms)
win-full
"C:\folder\another folder\file"
unix-relative
"folder/another folder/file" (works on both platforms)
unix-full
equal /folder/another folder/file"
FileMaker
Standard FileMaker file specification listed on File->Define->File References->New
URL
file://folder/another folder/file" (only URL of local files are accepted)

List of the most common error codes returned by 24U SimpleSound Plug-In's functions

-1 Recording is not in progress
-50 Invalid parameter
-1000 Plug-In requires registration (expired)
-9405 There is no recording device available