f10/sdk/fidl/fuchsia.media.sounds/README.md

<link rel="stylesheet" href="../style.css" />

[TOC]
# fuchsia.media.sounds

<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 7</span></div>


## **PROTOCOLS**

## Player {#Player}
*Defined in [fuchsia.media.sounds/sound_player.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.sounds/sound_player.fidl;l=14)*
<p>Allows clients to play fire-and-forget sounds.</p>


### AddSoundBuffer {#Player.AddSoundBuffer}

<p>Adds a sound, in the form of a buffer containing raw PCM samples, to the collection
maintained for the client. The service will retain a handle to the buffer's VMO until the
sound is removed and is no longer playing or until the connection is closed.</p>
<p>If <code>id</code> identifies an existing sound in the collection, the service will close the
connection.</p>



#### Request {#Player.AddSoundBuffer_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>id</code></td>
            <td>
                <code>uint32</code>
            </td>
        </tr>
        <tr>
            <td><code>buffer</code></td>
            <td>
                <code><a class='link' href='../fuchsia.mem/'>fuchsia.mem</a>/<a class='link' href='../fuchsia.mem/#Buffer'>Buffer</a></code>
            </td>
        </tr>
        <tr>
            <td><code>stream_type</code></td>
            <td>
                <code><a class='link' href='../fuchsia.media/'>fuchsia.media</a>/<a class='link' href='../fuchsia.media/#AudioStreamType'>AudioStreamType</a></code>
            </td>
        </tr>
</table>


### AddSoundFromFile {#Player.AddSoundFromFile}

<p>Adds a sound to the collection maintained for the client, reading the sound from a file.
If <code>id</code> identifies an existing sound in the collection, the service will close the
connection. Returns the duration of the sound or an error status returned from an I/O
operation.</p>
<p>Currently, only PCM WAV files and Ogg/Opus files are supported.</p>



#### Request {#Player.AddSoundFromFile_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>id</code></td>
            <td>
                <code>uint32</code>
            </td>
        </tr>
        <tr>
            <td><code>file</code></td>
            <td>
                <code><a class='link' href='../fuchsia.io/'>fuchsia.io</a>/<a class='link' href='../fuchsia.io/#File'>File</a></code>
            </td>
        </tr>
</table>


#### Response {#Player.AddSoundFromFile_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>result</code></td>
            <td>
                <code><a class='link' href='#Player_AddSoundFromFile_Result'>Player_AddSoundFromFile_Result</a></code>
            </td>
        </tr>
</table>

### PlaySound {#Player.PlaySound}

<p>Plays the existing sound identified by <code>id</code> using a renderer with usage <code>usage</code>. The
sound is played as soon as possible. The reply is sent when the sound is finished playing.
If <code>id</code> doesn't identify an existing sound in the collection, the method returns
<code>PlaySoundError.NO_SUCH_SOUND</code>. The most recent <code>PlaySound</code> call for a given valid id can
be stopped using <code>StopPlayingSound</code>, in which case, this method returns
<code>PlaySoundError.STOPPED</code>.</p>



#### Request {#Player.PlaySound_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>id</code></td>
            <td>
                <code>uint32</code>
            </td>
        </tr>
        <tr>
            <td><code>usage</code></td>
            <td>
                <code><a class='link' href='../fuchsia.media/'>fuchsia.media</a>/<a class='link' href='../fuchsia.media/#AudioRenderUsage'>AudioRenderUsage</a></code>
            </td>
        </tr>
</table>


#### Response {#Player.PlaySound_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>result</code></td>
            <td>
                <code><a class='link' href='#Player_PlaySound_Result'>Player_PlaySound_Result</a></code>
            </td>
        </tr>
</table>

### RemoveSound {#Player.RemoveSound}

<p>Removes a sound from the collection maintained for the client. A sound can be removed even
if a <code>PlaySound</code> method is pending for that sound.</p>
<p>If <code>id</code> doesn't identify an existing sound in the collection, the service will do nothing.
This is tolerated so that clients don't have to wait for the response from
<code>AddSoundFromFile</code> before playing and removing the sound.</p>
<p>Removing an unneeded sound frees the resources associated with that sound, principally
the VMO required to store the uncompressed sound.</p>



#### Request {#Player.RemoveSound_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>id</code></td>
            <td>
                <code>uint32</code>
            </td>
        </tr>
</table>


### StopPlayingSound {#Player.StopPlayingSound}

<p>Stops playback of the sound identified by <code>id</code> invoked by the the most recent call to
<code>PlaySound</code> for that sound. If <code>id</code> doesn't identify an existing sound in the collection
or if the sound is not currently playing, this method does nothing. If more than one
<code>PlaySound</code> method is currently pending for that sound, only the most recent is stopped.</p>



#### Request {#Player.StopPlayingSound_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>id</code></td>
            <td>
                <code>uint32</code>
            </td>
        </tr>
</table>



## **STRUCTS**

### Player_AddSoundFromFile_Response  {#Player_AddSoundFromFile_Response data-text="Player_AddSoundFromFile_Response"}
*Defined in [fuchsia.media.sounds/sound_player.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.sounds/sound_player.fidl;l=24)*

<table>
    <tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
        <tr id="Player_AddSoundFromFile_Response.duration">
            <td><code>duration</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#duration'>duration</a></code>
            </td>
            <td></td>
            <td>No default</td>
        </tr>
</table>

### Player_PlaySound_Response  {#Player_PlaySound_Response data-text="Player_PlaySound_Response"}
*Defined in [fuchsia.media.sounds/sound_player.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.sounds/sound_player.fidl;l=62)*

&lt;EMPTY&gt;


## **ENUMS**

### PlaySoundError [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#PlaySoundError data-text="PlaySoundError"}
Type: <code>uint32</code>

*Defined in [fuchsia.media.sounds/sound_player.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.sounds/sound_player.fidl;l=75)*
<p>Error type for <code>Player.PlaySound</code>.</p>

<table>
    <tr><th>Name</th><th>Value</th><th>Description</th></tr>
        <tr id="PlaySoundError.NO_SUCH_SOUND">
<td><h3 id="PlaySoundError.NO_SUCH_SOUND" class="add-link hide-from-toc">NO_SUCH_SOUND</h3></td>
            <td><code>1</code></td>
            <td><p>The <code>id</code> passed to <code>PlaySound</code> is not recognized.</p>
</td>
        </tr>
        <tr id="PlaySoundError.RENDERER_FAILED">
<td><h3 id="PlaySoundError.RENDERER_FAILED" class="add-link hide-from-toc">RENDERER_FAILED</h3></td>
            <td><code>2</code></td>
            <td><p>Underlying audio renderer failed.</p>
</td>
        </tr>
        <tr id="PlaySoundError.STOPPED">
<td><h3 id="PlaySoundError.STOPPED" class="add-link hide-from-toc">STOPPED</h3></td>
            <td><code>3</code></td>
            <td><p>Playback of the sound was interrupted by a |StopPlayingSound| method call.</p>
</td>
        </tr>
</table>



## **UNIONS**

### Player_AddSoundFromFile_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute}  {#Player_AddSoundFromFile_Result data-text="Player_AddSoundFromFile_Result"}
*Defined in [fuchsia.media.sounds/sound_player.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.sounds/sound_player.fidl;l=24)*
<table>
    <tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
        <tr id="Player_AddSoundFromFile_Result.response">
<td><h3 id="Player_AddSoundFromFile_Result.response" class="add-link hide-from-toc">1</h3></td>
            <td><code>response</code></td>
            <td>
                <code><a class='link' href='#Player_AddSoundFromFile_Response'>Player_AddSoundFromFile_Response</a></code>
            </td>
            <td></td>
        </tr>
        <tr id="Player_AddSoundFromFile_Result.err">
<td><h3 id="Player_AddSoundFromFile_Result.err" class="add-link hide-from-toc">2</h3></td>
            <td><code>err</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
            <td></td>
        </tr>
</table>

### Player_PlaySound_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute}  {#Player_PlaySound_Result data-text="Player_PlaySound_Result"}
*Defined in [fuchsia.media.sounds/sound_player.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.sounds/sound_player.fidl;l=62)*
<table>
    <tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
        <tr id="Player_PlaySound_Result.response">
<td><h3 id="Player_PlaySound_Result.response" class="add-link hide-from-toc">1</h3></td>
            <td><code>response</code></td>
            <td>
                <code><a class='link' href='#Player_PlaySound_Response'>Player_PlaySound_Response</a></code>
            </td>
            <td></td>
        </tr>
        <tr id="Player_PlaySound_Result.err">
<td><h3 id="Player_PlaySound_Result.err" class="add-link hide-from-toc">2</h3></td>
            <td><code>err</code></td>
            <td>
                <code><a class='link' href='#PlaySoundError'>PlaySoundError</a></code>
            </td>
            <td></td>
        </tr>
</table>