24U SimpleSound Plug-In 4.1 Syntax


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

Changes since SimpleSound 3.0

Since SimpleSound 3.0 recording functionality was removed as well as palindrome playing. Also error codes have been changed and some parameters have been changed or removed. You can highlight all the changes by button at the top of this page.

SSound_Version ( { versionFormat } )

Returns version string of the active 24U SimpleSound Plug-In, formatted as requested by the parameter.

Parameters

versionFormatDefines the format of the returned version.

Parameter values for versionFormat

"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.
"autoupdate" To get autoupdate compatible (comparable) version number.

Examples

SSound_Version( "long" )
This returns: "24U SimpleSound Plug-In 4.0".

SSound_Version( "platform" )
This returns: "Mac OS X" on OSX and "Windows" on windows.

SSound_Version( "short" )
This returns: "4.0".

SSound_Register(selector)

Provides special functionality to operate with plugin serial numbers.

Parameters

selectorDefine the type of operation.

Parameter values for selector

SerialNumber Register given SerialNumber and return an error code.
EmailAddress Tries to activate with given email address and return an error code. Trial version is valid only after you confirm email.
"Registration Window" Show the "Registration window" and return 0. This param does nothing on FileMaker Server.
"About Window" Show the "About window" and return 0. This param does nothing on FileMaker Server.
"Status" Return the actual registration state of the plugin: Demo, Demo expired, Trial, Trial Expired, Registered or Dead.
"Unregister" Unregister all serial numbers related to the product and return an error code. Note: after this trial version days wont come back.

Examples

SSound_Register( "address@example.com" )
This will send an email on address@example.com for confirmation. If you confirm it you will get trial version on this product verified by this email.

SSound_Register( "SND20C666-4B7B-37PH-Q2E6-1UKY" )
This will register the product with key: "SND20C666-4B7B-37PH-Q2E6-1UKY".

SSound_Register( "Unregister" )
This will remove all registered keys. After this call the product is no longer registered.

Result

Returns zero or error code depending on the selector.

SSound_Playback ( command ; sound {; offset} )

This function is used for controlling sounds playback.

This functionality is not available on FileMaker Server. It returns error code -4 (NotImplemented).

Parameter values for command

Name Description
"play synchronously" Until the sound stops FileMaker is "frozen".
"play" Start playing the sound from the offset position.
"loop" Start looping the sound from the offset position. (Until it is stopped).
"stop" Stops the sound playback. If called without sound param, it stops all playing and paused sounds.
"pause" The currently playing sound is paused.
"resume" When given a paused sound, the playback is resumed from the last position.

Parameter values for sound

Sound can be identified by a path to file or FileMaker container.

Parameter values for offset

Value for the offset is given in seconds (e.g. 2.45). The offset is the time, from which playback starts (has to be smaller than SSound_Get("length as seconds" ; sound) ).
Default value is 0.

Result

Returns zero or error code if an error occurs. Please see Error codes section.

Examples

SSound_Playback("loop" ; "/Users/john/Music/coolSong.mp3")
Starts playing coolSong.mp3 as loop over and over again.

SSound_Playback("play" ; "/Users/john/Music/coolSong.mp3")
Plays coolSong.mp3 only once.

SSound_Playback("play" ; SimpleSoundExample::songContainer)
Plays the sound placed in songContainer once.

SSound_Playback("play synchronously" ; "/Users/john/Music/coolSong.mp3")
Plays coolSong.mp3 only once, but until coolSong.mp3 stops, FileMaker will be frozen.

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

SSound_Get ( selector ; sound {; param1 {; param2} } )

This function allows to get information about plugin or about specific sound. See the table below for options.

Only ID3 tags work on FileMaker Server. Calling other defined values for selector causes return of error code -4 (NotImplemented).

Parameter values for selector

Name Sound param required? Description
"number of existing sounds" No Returns number of playing or paused sounds.
"number of playing sounds" No Returns number of playing sounds.
"length as time" Yes Returns length of the sound as hours, minutes and seconds.
"length as seconds" Yes Returns length of the sound in seconds.
"number of samples" Yes Returns number of samples.
"file format" Yes Returns format of the audio file. E.g. MPEG Audio.
"sampling rate" Yes Returns the sampling rate in Hz.
"number of channels" Yes Returns number of channels.
"list of contained picture types" Yes Returns list of all allocated picture types in sound.
"ID3 id3tagSelector" Yes Returns the value of specified ID3 tag.
"inlineDocumentation" No Returns status of inline documentation (values can be "on" or "off").
"bit rate" No longer supported.
"recording offset" No longer supported.
"recording options" No longer supported.
"quicktime version" No longer supported.
"recording status" No longer supported.
"data format" No longer supported.

Parameter values for id3tagSelector

Please replace the "id3tagSelector" with valid ID3v1 tag name or valid ID3v2 frame header. For supported values, please see section: About ID3

Parameter values for sound

Sound can be identified by path to file or FileMaker container.

Parameter meanings for param1

Selector MeaningOptionalDefault valueAdditional information
"ID3 USLT" languageyes""USLT allows to save more lyrics in different languages.
"ID3 APIC" APIC Typeyes"coverfront"Exact text representation of APIC Type is required.

Parameter meanings for param2

Selector MeaningOptionalDefault valueAdditional information
"ID3 USLT" descriptionyes"" This allows to add brief description for lyrics.

Result

Requested value or error code is returned. For information abou error codes please see Error codes section.

Examples

SSound_Get( "number of playing sounds" )
If no sound is playing it returns 0. Otherwise, it returns number of currently playing sounds.

SSound_Get( "ID3 USLT" ; "/Users/john/Music/coolSong.mp3" )
Gets the first USLT frame encountered.

SSound_Get( "ID3 USLT" ; "/Users/john/Music/coolSong.mp3" ; "eng")
Gets the USLT frame with language set to english.

SSound_Get( "ID3 USLT" ; "/Users/john/Music/coolSong.mp3" ; ""; "Rickroll lyrics")
Gets the USLT frame with given descriptor.

SSound_Get( "ID3 PCNT" ; "/Users/john/Music/coolSong.mp3")
Get value of play counter.

SSound_Get( "ID3 year" ; "/Users/john/Music/coolSong.mp3" )
Returns four characterss representing a year or "" if sound file doesn't have this ID3 tag set.

SSound_Get( "ID3 year" ; SimpleSoundExample::songContainer )
Returns four characters representing a year or "" if sound file in given container doesn't have this ID3 tag set.

SSound_Get( "ID3 TCOM" ; "/Users/john/Music/coolSong.mp3" )
Returns the stored info about the composer or an empty string if not available.

SSound_Get( "ID3 APIC" ; "/Users/john/Music/coolSong.mp3" ; "coverback" )
Returns image that is stored inside sound file under APIC Type "coverback" or returns error -64 if there is no such image.

SSound_Get( "ID3 APIC" ; "/Users/john/Music/coolSong.mp3" )
Returns image from sound file that is stored under APIC Type "coverfront". If there is no such image, plugin returns -64.

SSound_Get( "ID3 APIC" ; SimpleSoundExample::songContainer ; "media" )
Returns image that is stored under APIC Type "media" in sound container or returns error -64 if there is no such image.

SSound_Set ( selector ; value {; sound ; param1 {; param2} })

Allows to set ID3 tag value for specific sound.
Plugin directly modifies given sound file if the sound is passed using file path.
If the sound is passed via container new sound file is returned, so it can be stored into container.


Only ID3 tags work on FileMaker Server. Calling other defined values for selector causes return of error code -4 (NotImplemented).

Parameter values for selector

"ID3 id3tagSelector" Sound is mandatory for this value of selector.
"inlineDocumentation"
"recording options" No longer supported.

Parameter values for "id3tagSelector"

Please replace the "id3tagSelector" with valid ID3v1 tag name or valid ID3v2 frame header. For supported values, please see section: About ID3

Parameter values for value

Selector value Possible values
"ID3 id3tagSelector" Please read About ID3.
"inlineDocumentation" "on" or "off"

Parameter values for sound

Sound can be identified by path to file or FileMaker container.

Parameter meanings for param1

Selector MeaningOptionalDefault valueAdditional information
"ID3 USLT" languageyes"eng"
"ID3 APIC" APIC Typeyes"coverfront"Exact text representation of APIC Type is required.

Parameter meanings for param2

Selector MeaningOptionalDefault valueAdditional information
"ID3 USLT" descriptionyes""

Result

Value of selector Value of sound Result
"ID3 id3tagSelector" Path to file In case of success path to file is returned.
"ID3 id3tagSelector" Container with sound In case of success container with modified sound is returned.
"inlineDocumentation" Sound is ignored 0

In case of an error function returns error code. For information abou error codes please see Error codes section.

Examples

SSound_Set( "ID3 year" ; "2005" ; "/Users/john/Music/coolSong.mp3" )
Sets the value for year in ID3 tag of coolSong.mp3 to 2005.

SSound_Set( "ID3 USLT" ; "Never gonna give you up, never gonna let you down" ; "/Users/john/Music/coolSong.mp3")
Adding lyrics for sound with default language (eng) and no description.

SSound_Set( "ID3 USLT" ; "Never gonna give you up, never gonna let you down" ; "/Users/john/Music/coolSong.mp3" ; "eng" ; "Rickroll lyrics" )
Adding lyrics for sound with defined language (eng) and defined description (Rickroll lyrics).

SSound_Set( "ID3 PCNT" ; 33 ; "/Users/john/Music/coolSong.mp3" )
Sets value of play counter to 33.

SSound_Set( "inlineDocumentation" ; "on" )
Turns on inline documentation in calculation.

SSound_Set( "inlineDocumentation" ; "off" )
Turns off inline documentation in calculation.

SSound_Set( "ID3 APIC" ; SimpleSoundExample::imageContainer ; "/Users/john/Music/coolSong.mp3" ; "coverback" )
Sets image from container into sound file under APIC Type "coverback". If imageContainer (2nd parameter) is empty, image from "coverback" APIC Type will be removed. Note: Picture is removed, but id3lib still see this type as allocated.

SSound_Set( "ID3 APIC" ; SimpleSoundExample::imageContainer ; SimpleSoundExample::outputSoundContainer ; "composer" )
Sets image from 2nd parameter into sound file in 3rd parameter. Image is stored under "composer" APIC Type. If imageContainer (2nd parameter) is empty, image from "composer" APIC Type will be removed.

SSound_Set( "ID3 APIC" ; SimpleSoundExample::imageContainer ; SimpleSoundExample::outputSoundContainer )
Sets image from 2nd parameter into sound file in 3rd parameter. Image is stored under "coverfront" because no APIC Type is specified via 4th parameter. If imageContainer (2nd parameter) is empty, image from "coverfront" APIC Type will be removed.

About ID3 tags

ID3 is a metadata container, which can be used for storing information about sound (mostly .mp3 format).
There are two versions of ID3 tags:

Unfortunately these two versions aren't fully compatible. Furthermore, one of them or both can be present in the sound file. If sound file contains both ID3v1 and ID3v2.3, most players don't know which version to choose.

Behaviour of our plugin for ID3 tags:

More info about each version:

ID3 APIC

APIC is ID3 tag that supports storing image data inside sound file.

Image input/output
Embedded image only
Other APIC metadata
APIC types

Additional info

Supported formats on OSX

The plugin supports all formats supported by AVFoundation (for example: mp3, m4a and aac). These formats are supported for playback. List of all supported formats can be found here.

Supported formats on Windows

On Windows all formats provided by DirectShow filters currently installed on your system are supported. In case of missing filters only basic audio formats are supported (for example wav or mp3). List of all supported formats can be found here.

Different values

Different applications can use different ways for calculating length and number of samples. Our plugin uses AVFoundation (OSX) and DirectShow (Windows) for obtaining these values.

24U SimpleSound Plug-In Error codes

0Everything is fine
-4Not implemented
-50Means paramErr
-61Sound init failed Returned when trying to playing not sound file/container.
-62Control sound error Returned when trying to manipulating non-existing sound (e.g. trying to pause non-playing sound, trying to stop non-sound file.)
-63Offset too large Returned when given offset is larger then length of sound.
-64Not existing ID3 Requested ID3 tag doesn't exist.
-65Not supported ID3 version Requested ID3 tag is from not supported version (e.g. ID3V3 tags).
-66Not supported image MIME type or file extension Image's MIME type or file extension is not supported.
24001 Demo mode expired If you want to keep using the plug-in, you must register it or buy it for particular environment.
24002 Product expired Trial period is over. If you want to keep using the product, you must buy it for particular environment.
24003 SN limit was met The serial number is already registered on too many computers.
24004 Product is dead The product expired and cannot be used any more. Please download the new version from 24U Software.
24005 Invalid serial number Serial number you entered is not valid.
24006 Activation failed Activation failed probably due to some network error. Please, check your connection to the internet and try again later.
24007 Deactivation failed Deactivation failed probably due to some network error. Please, check your connection to the internet and try again later.
24008 Unknown serial number The given serial number cannot be used for the current product. It has been stored so that other product can try to use it.
24009 Blacklisted serial number The given serial number has been blacklisted and cannot be used anymore. Please, contact 24U Support if you need more information.
24010 eSellerate engine not installed This product uses eSellerate to validate user registration and purchases, but its installation failed. Please, reboot the computer or try again later.