blob: b60ef489dda8d2ca55044dabe2689b146b3c4ee7 [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.
@available(added=7)
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(resource struct {
id uint32;
file client_end:fuchsia.io.File;
}) -> (struct {
duration zx.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(resource struct {
id uint32;
buffer fuchsia.mem.Buffer;
stream_type fuchsia.media.AudioStreamType;
});
/// 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(struct {
id uint32;
});
/// 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(struct {
id uint32;
usage fuchsia.media.AudioRenderUsage;
}) -> (struct {}) 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(struct {
id uint32;
});
};
/// Error type for `Player.PlaySound`.
type PlaySoundError = strict enum {
/// 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;
};