Specification revision: 11, 2017-02-20.
Created by: Lukáš Liebzeit, ©2017 24U Software.
This file describes syntax of 24U SimpleSound Plug-In's functions.
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.
Returns version string of the active 24U SimpleSound Plug-In, formatted as requested by the parameter.
| versionFormat | Defines the format of the returned version. |
| "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. |
Returns requested version format or platform. If this function returns "?" than the plug-in is not properly installed or FileMaker cannot load and activate it for some reason.
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".
Provides special functionality to operate with plugin serial numbers.
| selector | Define the type of operation. |
| 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 |
| Hash | Activate a serial number with a hash received from 24U. Used for offline activation. |
| "Registration Window" | Show the "Registration window" and return 0. |
| "About Window" | Show the "About window" and return 0. |
| "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. |
| "Info" | Returns current plugin status and its registered serial numbers. |
| "ActivationChallenge" | Returns generated challenge string. This string is sent to 24U. |
| "Purchase" ; webAddress | Opens web browser with given webAddress. Given webAddress should point to 24U Store. This functionality is not implemented for FileMaker Server and Linux. |
Returns zero or error code depending on the selector.
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.
This function is used for controlling sounds playback.
This functionality is not available on FileMaker Server. It returns error code -4 (NotImplemented).
| 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. |
Sound can be identified by a path to file or FileMaker container.
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.
Returns zero or error code if an error occurs. Please see Error codes section.
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.
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).
| 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"). |
| No longer supported. | ||
| No longer supported. | ||
| No longer supported. | ||
| No longer supported. | ||
| No longer supported. | ||
| No longer supported. |
Please replace the "id3tagSelector" with valid ID3v1 tag name or valid ID3v2 frame header.
For supported values, please see section: About ID3
Sound can be identified by path to file or FileMaker container.
| Selector | Meaning | Optional | Default value | Additional information | |
|---|---|---|---|---|---|
| "ID3 USLT" | language | yes | "" | USLT allows to save more lyrics in different languages. | |
| "ID3 APIC" | APIC Type | yes | "coverfront" | Exact text representation of APIC Type is required. |
| Selector | Meaning | Optional | Default value | Additional information | ||
|---|---|---|---|---|---|---|
| "ID3 USLT" | description | yes | "" | This allows to add brief description for lyrics. |
Requested value or error code is returned. For information abou error codes please see Error codes section.
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.
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).
| "ID3 id3tagSelector" | Sound is mandatory for this value of selector. |
| "inlineDocumentation" | |
| No longer supported. |
Please replace the "id3tagSelector" with valid ID3v1 tag name or valid ID3v2 frame header.
For supported values, please see section: About ID3
| Selector value | Possible values |
|---|---|
| "ID3 id3tagSelector" | Please read About ID3. |
| "inlineDocumentation" | "on" or "off" |
Sound can be identified by path to file or FileMaker container.
| Selector | Meaning | Optional | Default value | Additional information | |
|---|---|---|---|---|---|
| "ID3 USLT" | language | yes | "eng" | ||
| "ID3 APIC" | APIC Type | yes | "coverfront" | Exact text representation of APIC Type is required. |
| Selector | Meaning | Optional | Default value | Additional information | |
|---|---|---|---|---|---|
| "ID3 USLT" | description | yes | "" |
| 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 |
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.
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:
| Name | Value | Equivalent ID3v2 tags |
|---|---|---|
| "title" | 30 basic ASCII chars | "TIT2" |
| "artist" | 30 basic ASCII chars | "TPE1" |
| "album" | 30 basic ASCII chars | "TALB" |
| "year" | 4 basic ASCII chars | "TYER" |
| "genre" | Number from 0 to 255 or one of text values. See table below. | "TCON" |
| "comment" | 30 basic ASCII chars | "COMM" |
APIC is ID3 tag that supports storing image data inside sound file.
Sound file can contain one image for each APIC Type (up to 20 images).
For specifying an APIC Type in 24U SimpleSound, use exact textual representattion from column "Type" from table shown using button below.
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.
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 applications can use different ways for calculating length and number of samples. Our plugin uses AVFoundation (OSX) and DirectShow (Windows) for obtaining these values.
| 0 | Everything is fine | |
| -4 | Not implemented | |
| -50 | Means paramErr | |
| -61 | Sound init failed | Returned when trying to playing not sound file/container. |
| -62 | Control sound error | Returned when trying to manipulating non-existing sound (e.g. trying to pause non-playing sound, trying to stop non-sound file.) |
| -63 | Offset too large | Returned when given offset is larger then length of sound. |
| -64 | Not existing ID3 | Requested ID3 tag doesn't exist. |
| -65 | Not supported ID3 version | Requested ID3 tag is from not supported version (e.g. ID3V3 tags). |
| -66 | Not 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. |