blob: 0dab4e2f2becaf9be22c7993dc9c9e3acf69c539 [file] [log] [blame]
// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.media.sounds;
using fuchsia.io;
using fuchsia.media;
using fuchsia.mem;
using zx;
/// Allows clients to play fire-and-forget sounds.
[Discoverable]
protocol Player {
/// Adds a sound to the collection maintained for the client, reading the sound from a file.
/// If `id` 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.
///
/// Currently, only PCM WAV files and Ogg/Opus files are supported.
AddSoundFromFile(uint32 id, fuchsia.io.File file) -> (zx.duration duration) error zx.status;
/// 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.
///
/// If `id` identifies an existing sound in the collection, the service will close the
/// connection.
AddSoundBuffer(uint32 id, fuchsia.mem.Buffer buffer, fuchsia.media.AudioStreamType stream_type);
/// Removes a sound from the collection maintained for the client. A sound can be removed even
/// if a `PlaySound` method is pending for that sound.
///
/// If `id` 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
/// `AddSoundFromFile` before playing and removing the sound.
///
/// Removing an unneeded sound frees the resources associated with that sound, principally
/// the VMO required to store the uncompressed sound.
RemoveSound(uint32 id);
/// Plays the existing sound identified by `id` using a renderer with usage `usage`. The
/// sound is played as soon as possible. The reply is sent when the sound is finished playing.
/// If `id` doesn't identify an existing sound in the collection, the method returns
/// `PlaySoundError.NO_SUCH_SOUND`. The most recent `PlaySound` call for a given valid id can
/// be stopped using `StopPlayingSound`, in which case, this method returns
/// `PlaySoundError.STOPPED`.
PlaySound(uint32 id, fuchsia.media.AudioRenderUsage usage) -> () error PlaySoundError;
/// Stops playback of the sound identified by `id` invoked by the the most recent call to
/// `PlaySound` for that sound. If `id` 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
/// `PlaySound` method is currently pending for that sound, only the most recent is stopped.
[Transitional]
StopPlayingSound(uint32 id);
};
/// Error type for `Player.PlaySound`.
enum PlaySoundError {
/// The `id` passed to `PlaySound` is not recognized.
NO_SUCH_SOUND = 1;
/// Underlying audio renderer failed.
RENDERER_FAILED = 2;
/// Playback of the sound was interrupted by a |StopPlayingSound| method call.
STOPPED = 3;
};