import Future from "../utils/Future"; import ByteArray from "../utils/ByteArray"; import URLRequest from "../net/URLRequest"; import SoundTransform from "./SoundTransform"; import SoundLoaderContext from "./SoundLoaderContext"; import SoundChannel from "./SoundChannel"; import ID3Info from "./ID3Info"; import EventDispatcher from "../events/EventDispatcher"; declare namespace openfl.media { /** * The Sound class lets you work with sound in an application. The Sound class * lets you create a Sound object, load and play an external MP3 file into * that object, close the sound stream, and access data about the sound, such * as information about the number of bytes in the stream and ID3 metadata. * More detailed control of the sound is performed through the sound source * - the SoundChannel or Microphone object for the sound — and through the * properties in the SoundTransform class that control the output of the sound * to the computer's speakers. * * In Flash Player 10 and later and AIR 1.5 and later, you can also use * this class to work with sound that is generated dynamically. In this case, * the Sound object uses the function you assign to a `sampleData` * event handler to poll for sound data. The sound is played as it is * retrieved from a ByteArray object that you populate with sound data. You * can use `Sound.extract()` to extract sound data from a Sound * object, after which you can manipulate it before writing it back to the * stream for playback. * * To control sounds that are embedded in a SWF file, use the properties in * the SoundMixer class. * * **Note**: The OpenFL Sound API differs from ActionScript * 2.0. In OpenFL, you cannot take sound objects and arrange them in * a hierarchy to control their properties. * * When you use this class, consider the following security model: * * * * Loading and playing a sound is not allowed if the calling file is in * a network sandbox and the sound file to be loaded is local. * * By default, loading and playing a sound is not allowed if the calling * file is local and tries to load and play a remote sound. A user must grant * explicit permission to allow this type of access. * * Certain operations dealing with sound are restricted. The data in a * loaded sound cannot be accessed by a file in a different domain unless you * implement a cross-domain policy file. Sound-related APIs that fall under * this restriction are `Sound.id3`, * `SoundMixer.computeSpectrum()`, * `SoundMixer.bufferTime`, and the `SoundTransform` * class. * * * However, in Adobe AIR, content in the `application` security * sandbox (content installed with the AIR application) are not restricted by * these security limitations. * * For more information related to security, see the Flash Player Developer * Center Topic: [Security](http://www.adobe.com/go/devnet_security_en). * * @event complete Dispatched when data has loaded successfully. * @event id3 Dispatched by a Sound object when ID3 data is available * for an MP3 sound. * @event ioError Dispatched when an input/output error occurs that causes * a load operation to fail. * @event open Dispatched when a load operation starts. * @event progress Dispatched when data is received as a load operation * progresses. * @event sampleData Dispatched when the runtime requests new audio data. * * @see [Working with sound](https://books.openfl.org/openfl-developers-guide/working-with-sound/) * @see [Playing sounds](https://books.openfl.org/openfl-developers-guide/working-with-sound/playing-sounds.html) * @see [Loading external sound files](https://books.openfl.org/openfl-developers-guide/working-with-sound/loading-external-sound-files.html) * @see [Working with sound assets](https://books.openfl.org/openfl-developers-guide/working-with-sound/working-with-sound-assets.html) * @see [Controlling sound volume and panning](https://books.openfl.org/openfl-developers-guide/working-with-sound/controlling-sound-volume-and-panning.html) * @see [Working with dynamically generated audio](https://books.openfl.org/openfl-developers-guide/working-with-sound/working-with-dynamically-generated-audio.html) * */ export class Sound extends EventDispatcher { /** * Creates a new Sound object. If you pass a valid URLRequest object to the * Sound constructor, the constructor automatically calls the * `load()` function for the Sound object. If you do not pass a * valid URLRequest object to the Sound constructor, you must call the * `load()` function for the Sound object yourself, or the stream * will not load. * * Once `load()` is called on a Sound object, you can't later * load a different sound file into that Sound object. To load a different * sound file, create a new Sound object. * In Flash Player 10 and later and AIR 1.5 and later, instead of using * `load()`, you can use the `sampleData` event handler * to load sound dynamically into the Sound object. * * @param stream The URL that points to an external MP3 file. * @param context An optional SoundLoader context object, which can define * the buffer time (the minimum number of milliseconds of MP3 * data to hold in the Sound object's buffer) and can specify * whether the application should check for a cross-domain * policy file prior to loading the sound. * */ constructor(stream?: URLRequest, context?: SoundLoaderContext); /** * Creates a new Sound from an AudioBuffer immediately. * * @param buffer An AudioBuffer instance * @returns A new Sound * */ static fromAudioBuffer(buffer: any): Sound; /** * Creates a new Sound from a file path synchronously. This means that the * Sound will be returned immediately (if supported). * * HTML5 and Flash do not support creating Sound synchronously, so these targets * always return `null`. * * In order to load files from a remote web address, use the `loadFromFile` method, * which supports asynchronous loading. * * @param path A local file path containing a sound * @returns A new Sound if successful, or `null` if unsuccessful * */ static fromFile(path: string): Sound; /** * Creates a new Sound from a file path or web address asynchronously. The file * load will occur in the background. * * Progress, completion and error callbacks will be dispatched in the current * thread using callbacks attached to a returned Future object. * * @param path A local file path or web address containing a sound * @returns A Future Sound * */ static loadFromFile(path: string): Future; /** * Creates a new Sound from a set of file paths or web addresses asynchronously. * The audio backend will choose the first compatible file format, and will load the file * it selects in the background. * * Progress, completion and error callbacks will be dispatched in the current * thread using callbacks attached to a returned Future object. * * @param paths A set of local file paths or web addresses containing sound * @returns A Future Sound * */ static loadFromFiles(paths: Array): Future; /** * Returns the currently available number of bytes in this sound object. This * property is usually useful only for externally loaded files. * */ bytesLoaded: number; /** * Returns the total number of bytes in this sound object. * */ bytesTotal: number; /** * Provides access to the metadata that is part of an MP3 file. * MP3 sound files can contain ID3 tags, which provide metadata about the * file. If an MP3 sound that you load using the `Sound.load()` method * contains ID3 tags, you can query these properties. Only ID3 tags that * use the UTF-8 character set are supported. * * Flash Player 9 and later and AIR support ID3 2.0 tags, specifically * 2.3 and 2.4. The following tables list the standard ID3 2.0 tags and * the type of content the tags represent. The `Sound.id3` property * provides access to these tags through the format `my_sound.id3.COMM`, * `my_sound.id3.TIME`, and so on. The first table describes tags that * can be accessed either through the ID3 2.0 property name or the * Haxe property name. The second table describes ID3 tags that * are supported but do not have predefined properties in Haxe. * * | ID3 2.0 tag | Corresponding Sound class property | * | --- | --- | * | COMM | Sound.id3.comment | * | TALB | Sound.id3.album | * | TCON | Sound.id3.genre | * | TIT2 | Sound.id3.songName | * | TPE1 | Sound.id3.artist | * | TRCK | Sound.id3.track | * | TYER | Sound.id3.year | * * The following table describes ID3 tags that are supported but do not * have predefined properties in the Sound class. You access them by * calling `mySound.id3.TFLT`, `mySound.id3.TIME`, and so on. **NOTE:** * None of these tags are supported in Flash Lite 4. * * | Property | Description | * | --- | --- | * | TFLT | File type | * | TIME | Time | * | TIT1 | Content group description | * | TIT2 | Title/song name/content description | * | TIT3 | Subtitle/description refinement | * | TKEY | Initial key | * | TLAN | Languages | * | TLEN | Length | * | TMED | Media type | * | TOAL | Original album/movie/show title | * | TOFN | Original filename | * | TOLY | Original lyricists/text writers | * | TOPE | Original artists/performers | * | TORY | Original release year | * | TOWN | File owner/licensee | * | TPE1 | Lead performers/soloists | * | TPE2 | Band/orchestra/accompaniment | * | TPE3 | Conductor/performer refinement | * | TPE4 | Interpreted, remixed, or otherwise modified by | * | TPOS | Part of a set | * | TPUB | Publisher | * | TRCK | Track number/position in set | * | TRDA | Recording dates | * | TRSN | Internet radio station name | * | TRSO | Internet radio station owner | * | TSIZ | Size | * | TSRC | ISRC (international standard recording code) | * | TSSE | Software/hardware and settings used for encoding | * | TYER | Year | * | WXXX | URL link frame | * * When using this property, consider the Flash Player security model: * * * The `id3` property of a Sound object is always permitted for SWF * files that are in the same security sandbox as the sound file. For * files in other sandboxes, there are security checks. * * When you load the sound, using the `load()` method of the Sound * class, you can specify a `context` parameter, which is a * SoundLoaderContext object. If you set the `checkPolicyFile` property * of the SoundLoaderContext object to `true`, Flash Player checks for a * URL policy file on the server from which the sound is loaded. If a * policy file exists and permits access from the domain of the loading * SWF file, then the file is allowed to access the `id3` property of the * Sound object; otherwise it is not. * * However, in Adobe AIR, content in the `application` security sandbox * (content installed with the AIR application) are not restricted by * these security limitations. * * For more information related to security, see the Flash Player * Developer Center Topic: [Security](http://www.adobe.com/go/devnet_security_en). * */ get id3(): ID3Info; /** * Returns the buffering state of external MP3 files. If the value is * `true`, any playback is currently suspended while the object * waits for more data. * */ isBuffering: boolean; /** * The length of the current sound in milliseconds. * */ get length(): number; /** * The URL from which this sound was loaded. This property is applicable only * to Sound objects that were loaded using the `Sound.load()` * method. For Sound objects that are associated with a sound asset from a * SWF file's library, the value of the `url` property is * `null`. * * When you first call `Sound.load()`, the `url` * property initially has a value of `null`, because the final URL * is not yet known. The `url` property will have a non-null value * as soon as an `open` event is dispatched from the Sound * object. * * The `url` property contains the final, absolute URL from * which a sound was loaded. The value of `url` is usually the * same as the value passed to the `stream` parameter of * `Sound.load()`. However, if you passed a relative URL to * `Sound.load()` the value of the `url` property * represents the absolute URL. Additionally, if the original URL request is * redirected by an HTTP server, the value of the `url` property * reflects the final URL from which the sound file was actually downloaded. * This reporting of an absolute, final URL is equivalent to the behavior of * `LoaderInfo.url`. * * In some cases, the value of the `url` property is truncated; * see the `isURLInaccessible` property for details. * */ url: string; get sampleRate(): number; /** * Closes the stream, causing any download of data to cease. No data may * be read from the stream after the `close()` method is called. * * @throws IOError The stream could not be closed, or the stream was not * open. * */ close(): void; /** * Initiates loading of an external MP3 file from the specified URL. If you * provide a valid URLRequest object to the Sound constructor, the * constructor calls `Sound.load()` for you. You only need to call * `Sound.load()` yourself if you don't pass a valid URLRequest * object to the Sound constructor or you pass a `null` value. * * Once `load()` is called on a Sound object, you can't later * load a different sound file into that Sound object. To load a different * sound file, create a new Sound object. * * When using this method, consider the following security model: * * * Calling `Sound.load()` is not allowed if the calling file * is in the local-with-file-system sandbox and the sound is in a network * sandbox. * * Access from the local-trusted or local-with-networking sandbox * requires permission from a website through a URL policy file. * * You cannot connect to commonly reserved ports. For a complete list * of blocked ports, see "Restricting Networking APIs" in the _OpenFL * Developer's Guide_. * * You can prevent a SWF file from using this method by setting the * `allowNetworking` parameter of the `object` and * `embed` tags in the HTML page that contains the SWF * content. * * In Flash Player 10 and later, if you use a multipart Content-Type (for * example "multipart/form-data") that contains an upload (indicated by a * "filename" parameter in a "content-disposition" header within the POST * body), the POST operation is subject to the security rules applied to * uploads: * * * The POST operation must be performed in response to a user-initiated * action, such as a mouse click or key press. * * If the POST operation is cross-domain (the POST target is not on the * same server as the SWF file that is sending the POST request), the target * server must provide a URL policy file that permits cross-domain * access. * * * Also, for any multipart Content-Type, the syntax must be valid * (according to the RFC2046 standards). If the syntax appears to be invalid, * the POST operation is subject to the security rules applied to * uploads. * * In Adobe AIR, content in the `application` security sandbox * (content installed with the AIR application) are not restricted by these * security limitations. * * For more information related to security, see the Flash Player * Developer Center Topic: [Security](http://www.adobe.com/go/devnet_security_en). * * @param stream A URL that points to an external MP3 file. * @param context An optional SoundLoader context object, which can define * the buffer time (the minimum number of milliseconds of MP3 * data to hold in the Sound object's buffer) and can specify * whether the application should check for a cross-domain * policy file prior to loading the sound. * @throws IOError A network error caused the load to fail. * @throws IOError The `digest` property of the * `stream` object is not `null`. * You should only set the `digest` property * of a URLRequest object when calling the * `URLLoader.load()` method when loading a * SWZ file (an Adobe platform component). * @throws SecurityError Local untrusted files may not communicate with the * Internet. You can work around this by reclassifying * this file as local-with-networking or trusted. * @throws SecurityError You cannot connect to commonly reserved ports. For a * complete list of blocked ports, see "Restricting * Networking APIs" in the _OpenFL * Developer's Guide_. * * @see [Loading external sound files](https://books.openfl.org/openfl-developers-guide/working-with-sound/loading-external-sound-files.html) * */ load(stream: URLRequest, context?: SoundLoaderContext): void; /** * Load MP3 sound data from a ByteArray object into a Sound object. The data will be read from the current * ByteArray position and will leave the ByteArray position at the end of the specified bytes length once * finished. If the MP3 sound data contains ID3 data ID3 events will be dispatched during this function call. * This function will throw an exception if the ByteArray object does not contain enough data. * * @param bytes * @param bytesLength * */ loadCompressedDataFromByteArray(bytes: ByteArray, bytesLength: number): void; /** * Load PCM 32-bit floating point sound data from a ByteArray object into a Sound object. The data will be read * from the current ByteArray position and will leave the ByteArray position at the end of the specified sample * length multiplied by either 1 channel or 2 channels if the stereo flag is set once finished. * * Starting with Flash Player 11.8, the amount of audio data that can be passed to this function is limited. For * SWF versions >= 21, this function throws an exception if the amount of audio data passed into this function is * more than 1800 seconds. That is, samples / sampleRate should be less than or equal to 1800. For swf versions < * 21, the runtime fails silently if the amount of audio data passed in is more than 12000 seconds. This is * provided only for backward compatibility. * * This function throws an exception if the ByteArray object does not contain enough data. * * @param bytes * @param samples * @param format * @param stereo * @param sampleRate * */ loadPCMFromByteArray(bytes: ByteArray, samples: number, format?: string, stereo?: boolean, sampleRate?: number): void; /** * Generates a new SoundChannel object to play back the sound. This method * returns a SoundChannel object, which you access to stop the sound and to * monitor volume.(To control the volume, panning, and balance, access the * SoundTransform object assigned to the sound channel.) * * @param startTime The initial position in milliseconds at which playback * should start. * @param loops Defines the number of times a sound loops back to the * `startTime` value before the sound channel * stops playback. * @param sndTransform The initial SoundTransform object assigned to the * sound channel. * @return A SoundChannel object, which you use to control the sound. This * method returns `null` if you have no sound card or if * you run out of available sound channels. The maximum number of * sound channels available at once is 32. * * @see [Playing sounds](https://books.openfl.org/openfl-developers-guide/working-with-sound/playing-sounds.html) * */ play(startTime?: number, loops?: number, sndTransform?: SoundTransform): SoundChannel; } } export default openfl.media.Sound;