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} )
Please, read limitations.
| |
SSound_Recording( controlcommand)
Please, read limitations.
| 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)
Please, read limitations.
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)
Please, read limitations.
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.
Please, read limitations.
|
| |
"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.
Please, read limitations.
|
| |
"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.
Please, read limitations.
|
| | | |
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.
Please, read limitations.
| 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.
- sound residing on the HD, specified by filespec
- 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 |
| -4 | | Not implemented |
| -43 | | Nonexistent sound file was specified |
| -35 | | Sound file on non-existent volume was specified |
| -50 | | Invalid parameter |
| -1000 | | Plug-In requires registration (expired) |
| -2048 | | invalid sound file was specified |
| -9405 | | There is no recording device available |
Limitations
Recording is not available in plugin version 3.0.2 on FileMaker 13 on Mac (it returns error -4). All other configurations work unchanged.