Player Class Reference

A Player contains a loaded audio file and a command API for manipulating it. More...

#include <player.hpp>

Collaboration diagram for Player:

Public Types
using	SinkFn = std::function< std::unique_ptr< AudioSink >(const AudioSource &, int)>
	Type for functions that construct sinks.
using	SourceFn = std::function< std::unique_ptr< AudioSource >(const std::string &)>
	Type for functions that construct sources.

Public Member Functions
	Player (int device_id, SinkFn sink, std::map< std::string, SourceFn > sources)
	Constructs a Player. More...
	Player (const Player &)=delete
	Deleted copy constructor.
Player &	operator= (const Player &)=delete
	Deleted copy-assignment constructor.
void	SetIo (ResponseSink &io)
	Sets the ResponseSink to which this Player shall send responses. More...
bool	Update ()
	Instructs the Player to perform a cycle of work. More...
Response	SetPlaying (const std::string &tag, bool playing)
	Tells the audio file to start or stop playing. More...
Response	Dump (size_t id, const std::string &tag) const
	Dumps the current player state to the given ID. More...
Response	Eject (const std::string &tag)
	Ejects the current loaded song, if any. More...
Response	End (const std::string &tag)
	Ends a file, stopping and rewinding. More...
Response	Load (const std::string &tag, const std::string &path)
	Loads a file. More...
Response	Pos (const std::string &tag, const std::string &pos_str)
	Seeks to a given position in the current file. More...
Response	Quit (const std::string &tag)
	Quits playd. More...

Private Member Functions
void	PosRaw (const std::string &tag, std::uint64_t pos)
	Performs an actual seek. More...
void	DumpState (size_t id, const std::string &tag) const
	Emits a response for the current audio state to the sink. More...
void	Respond (int id, Response rs) const
	Outputs a response, if there is a ResponseSink attached. More...
bool	CanAnnounceTime (std::uint64_t micros)
	Determines whether we can broadcast a POS response. More...
std::unique_ptr< Audio >	LoadRaw (const std::string &path) const
	Loads a file, creating an Audio for it. More...
std::unique_ptr< AudioSource >	LoadSource (const std::string &path) const
	Loads a file, creating an AudioSource. More...

Static Private Member Functions
static std::uint64_t	PosParse (const std::string &pos_str)
	Parses pos_str as a seek timestamp. More...

Private Attributes
int	device_id
	The sink's device ID.
SinkFn	sink
	The sink create function.
std::map< std::string, SourceFn >	sources
	The file formats map.
std::unique_ptr< Audio >	file
	The loaded audio file.
bool	dead
	Whether the Player is closing.
const ResponseSink *	io
	The sink for responses.
std::uint64_t	last_pos
	The last-sent position.

Detailed Description

A Player contains a loaded audio file and a command API for manipulating it.

See also

Audio

AudioSystem

Definition at line 31 of file player.hpp.

Constructor & Destructor Documentation

Player()

Player::Player	(	int	device_id,
		SinkFn	sink,
		std::map< std::string, SourceFn >	sources
	)

Constructs a Player.

Parameters

device_id	The device ID to which sinks shall output.
sink	The function to be used for building sinks.
sources	The map of file extensions to functions used for building sources.

Definition at line 25 of file player.cpp.

    : device_id(device_id),
      sink(std::move(sink)),
      sources(std::move(sources)),
      file(std::make_unique<NoAudio>()),
      dead(false),
      io(nullptr),
      last_pos(0)
{
}

Member Function Documentation

CanAnnounceTime()

bool Player::CanAnnounceTime ( std::uint64_t  micros )

private

Determines whether we can broadcast a POS response.

To prevent spewing massive amounts of POS responses, we only send a broadcast if the number of seconds has changed since the last time CanAnnounceTime() was called.

This is not idempotent. A CanAnnounceTime(x) less than one second before a CanAnnounceTime(x) will always be false.

Parameters

micros

The value of the POS response, in microseconds.

Returns

Whether it is polite to broadcast POS.

Definition at line 295 of file player.cpp.

References last_pos.

Referenced by Update().

{
    std::uint64_t secs = micros / 1000 / 1000;

    // We can announce if the last announced pos was in a previous second.
    bool announce = this->last_pos < secs;
    if (announce) this->last_pos = secs;

    return announce;
}

Dump()

Response Player::Dump	(	size_t	id,
		const std::string &	tag
	)		const

Dumps the current player state to the given ID.

Parameters

id	The ID of the connection to which the Player should route any responses. For broadcasts, use 0.
tag	The tag of the request calling this command. For unsolicited dumps, use Response::NOREQUEST.

Returns

The result of dumping, which is always success.

Definition at line 65 of file player.cpp.

References dead, DumpState(), Response::Failure(), file, Response::FLOAD, MSG_CMD_PLAYER_CLOSING, Audio::NONE, Response::POS, Respond(), and Response::Success().

Referenced by Load(), and Connection::RunCommand().

{
    if (this->dead) return Response::Failure(tag, MSG_CMD_PLAYER_CLOSING);

    this->DumpState(id, tag);

    // This information won't exist if there is no file.
    if (this->file->CurrentState() != Audio::State::NONE) {
        auto file = this->file->File();
        this->Respond(
                id, Response(tag, Response::Code::FLOAD).AddArg(file));

        auto pos = this->file->Position();
        this->Respond(id, Response(tag, Response::Code::POS)
                                  .AddArg(std::to_string(pos)));
    }

    return Response::Success(tag);
}

DumpState()

void Player::DumpState ( size_t  id, const std::string &  tag  ) const

private

Emits a response for the current audio state to the sink.

Parameters

id	The ID of the connection to which the Player should route any responses. For broadcasts, use 0.
tag	The tag of the request calling this command. For unsolicited dumps, use Response::NOREQUEST.

See also

DumpRaw

Definition at line 265 of file player.cpp.

References Audio::AT_END, Response::EJECT, Response::END, file, Audio::NONE, Response::PLAY, Audio::PLAYING, Respond(), Response::STOP, and Audio::STOPPED.

Referenced by Dump(), Eject(), and SetPlaying().

{
    Response::Code code = Response::Code::EJECT;

    switch (this->file->CurrentState()) {
        case Audio::State::AT_END:
            code = Response::Code::END;
            break;
        case Audio::State::NONE:
            code = Response::Code::EJECT;
            break;
        case Audio::State::PLAYING:
            code = Response::Code::PLAY;
            break;
        case Audio::State::STOPPED:
            code = Response::Code::STOP;
            break;
        default:
            // Just don't dump anything in this case.
            return;
    }

    this->Respond(id, Response(tag, code));
}

Eject()

Response Player::Eject

(

const std::string &

tag

)

Ejects the current loaded song, if any.

Parameters

tag	The tag of the request calling this command. For unsolicited ejects, use Response::NOREQUEST.

Returns

Whether the ejection succeeded.

Definition at line 85 of file player.cpp.

References dead, DumpState(), Response::Failure(), file, MSG_CMD_PLAYER_CLOSING, Audio::NONE, and Response::Success().

Referenced by Load(), Quit(), and Connection::RunCommand().

{
    if (this->dead) return Response::Failure(tag, MSG_CMD_PLAYER_CLOSING);

    // Silently ignore ejects on ejected files.
    // Concurrently speaking, this should be fine, as we are the only
    // thread that can eject or un-eject files.
    if (this->file->CurrentState() == Audio::State::NONE) {
        return Response::Success(tag);
    }

    assert(this->file != nullptr);
    this->file = std::make_unique<NoAudio>();

    this->DumpState(0, tag);

    return Response::Success(tag);
}

End()

Response Player::End

(

const std::string &

tag

)

Ends a file, stopping and rewinding.

Parameters

tag	The tag of the request calling this command. For unsolicited ends, use Response::NOREQUEST.

Returns

Whether the end succeeded.

Definition at line 104 of file player.cpp.

References dead, Response::END, Response::Failure(), MSG_CMD_PLAYER_CLOSING, Response::NOREQUEST, PosRaw(), Respond(), SetPlaying(), and Response::Success().

Referenced by Pos(), Connection::RunCommand(), and Update().

{
    if (this->dead) return Response::Failure(tag, MSG_CMD_PLAYER_CLOSING);

    // Let upstream know that the file ended by itself.
    // This is needed for auto-advancing playlists, etc.
    this->Respond(0, Response(Response::NOREQUEST, Response::Code::END));

    this->SetPlaying(tag, false);

    // Rewind the file back to the start.  We can't use Player::Pos() here
    // in case End() is called from Pos(); a seek failure could start an
    // infinite loop.
    this->PosRaw(Response::NOREQUEST, 0);

    return Response::Success(tag);
}

Load()

Response Player::Load	(	const std::string &	tag,
		const std::string &	path
	)

Loads a file.

Parameters

tag	The tag of the request calling this command. For unsolicited loads, use Response::NOREQUEST.
path	The absolute path to a track to load.

Returns

Whether the load succeeded.

Definition at line 122 of file player.cpp.

References dead, Dump(), Eject(), Response::Failure(), file, Response::Invalid(), last_pos, LoadRaw(), Error::Message(), MSG_CMD_PLAYER_CLOSING, MSG_LOAD_EMPTY_PATH, Response::NOREQUEST, and Response::Success().

Referenced by Connection::RunCommand().

{
    if (this->dead) return Response::Failure(tag, MSG_CMD_PLAYER_CLOSING);
    if (path.empty()) return Response::Invalid(tag, MSG_LOAD_EMPTY_PATH);

    assert(this->file != nullptr);

    // Bin the current file as soon as possible.
    // This ensures that we don't have any situations where two files are
    // contending over resources, or the current file spends a second or
    // two flushing its remaining audio.
    this->Eject(Response::NOREQUEST);

    try {
        this->file = this->LoadRaw(path);
    } catch (FileError &e) {
        // File errors aren't fatal, so catch them here.
        return Response::Failure(tag, e.Message());
    }

    assert(this->file != nullptr);
    this->last_pos = 0;

    // A load will change all of the player's state in one go,
    // so just send a Dump() instead of writing out all of the responses
    // here.
    // Don't take the response from here, though, because it has the wrong
    // tag.
    this->Dump(0, Response::NOREQUEST);

    return Response::Success(tag);
}

LoadRaw()

std::unique_ptr< Audio > Player::LoadRaw ( const std::string &  path ) const

private

Loads a file, creating an Audio for it.

Parameters

path	The path to a file.

Returns

A unique pointer to the Audio for that file.

Definition at line 306 of file player.cpp.

References device_id, LoadSource(), and sink.

Referenced by Load().

{
    std::unique_ptr<AudioSource> source = this->LoadSource(path);
    assert(source != nullptr);

    auto sink = this->sink(*source, this->device_id);
    return std::make_unique<PipeAudio>(std::move(source), std::move(sink));
}

LoadSource()

std::unique_ptr< AudioSource > Player::LoadSource ( const std::string &  path ) const

private

Loads a file, creating an AudioSource.

Parameters

path	The path to the file to load.

Returns

An AudioSource pointer (may be nullptr, if no available and suitable AudioSource was found).

See also

Load

Definition at line 315 of file player.cpp.

References sources.

Referenced by LoadRaw().

{
    size_t extpoint = path.find_last_of('.');
    std::string ext = path.substr(extpoint + 1);

    auto ibuilder = this->sources.find(ext);
    if (ibuilder == this->sources.end()) {
        throw FileError("Unknown file format: " + ext);
    }

    return (ibuilder->second)(path);
}

Pos()

Response Player::Pos	(	const std::string &	tag,
		const std::string &	pos_str
	)

Seeks to a given position in the current file.

Parameters

tag	The tag of the request calling this command. For unsolicited seeks, use Response::NOREQUEST.
pos_str	A string containing a timestamp, in microseconds

Returns

Whether the seek succeeded.

Definition at line 155 of file player.cpp.

References dead, End(), Response::Failure(), Response::Invalid(), Error::Message(), MSG_CMD_NEEDS_LOADED, MSG_CMD_PLAYER_CLOSING, PosParse(), PosRaw(), and Response::Success().

Referenced by Connection::RunCommand().

{
    if (this->dead) return Response::Failure(tag, MSG_CMD_PLAYER_CLOSING);

    std::uint64_t pos = 0;
    try {
        pos = PosParse(pos_str);
    } catch (SeekError &e) {
        // Seek errors here are a result of clients sending weird times.
        // Thus, we tell them off.
        return Response::Invalid(tag, e.Message());
    }

    try {
        this->PosRaw(tag, pos);
    } catch (NoAudioError) {
        return Response::Invalid(tag, MSG_CMD_NEEDS_LOADED);
    } catch (SeekError) {
        // Seek failures here are a result of the decoder not liking the
        // seek position (usually because it's outside the audio file!).
        // Thus, unlike above, we try to recover.

        Debug() << "Seek failure" << std::endl;

        // Make it look to the client as if the seek ran off the end of
        // the file.
        this->End(tag);
    }

    // If we've made it all the way down here, we deserve to succeed.
    return Response::Success(tag);
}

PosParse()

std::uint64_t Player::PosParse ( const std::string &  pos_str )

staticprivate

Parses pos_str as a seek timestamp.

Parameters

pos_str

The time string to be parsed.

Returns

The parsed time.

Exceptions

std::out_of_range	See http://www.cplusplus.com/reference/string/stoull/#exceptions
std::invalid_argument	See http://www.cplusplus.com/reference/string/stoull/#exceptions
SeekError	Raised if checks beyond those done by stoull fail.

Definition at line 223 of file player.cpp.

References MSG_SEEK_INVALID_VALUE.

Referenced by Pos().

{
    size_t cpos = 0;

    // Try and see if this position string is negative.
    // Cheap and easy way: see if it has '-'.
    // This means we don't need to skip whitespace first, with no loss
    // of suction: no valid position string will contain '-'.
    if (pos_str.find('-') != std::string::npos) {
        throw SeekError(MSG_SEEK_INVALID_VALUE);
    }


    std::uint64_t pos;
    try {
        pos = std::stoull(pos_str, &cpos);
    } catch (...) {
        throw SeekError(MSG_SEEK_INVALID_VALUE);
    }

    // cpos will point to the first character in pos that wasn't a number.
    // We don't want any such characters here, so bail if the position isn't
    // at the end of the string.
    auto sl = pos_str.length();
    if (cpos != sl) throw SeekError(MSG_SEEK_INVALID_VALUE);

    return pos;
}

PosRaw()

void Player::PosRaw ( const std::string &  tag, std::uint64_t  pos  )

private

Performs an actual seek.

This does not do any EOF handling.

Parameters

tag	The tag of the request calling this command. For unsolicited seeks, use Response::NOREQUEST.
pos	The new position, in microseconds.

Exceptions

SeekError

Raised if the seek is out of range (usually EOF).

See also

Player::Seek

Definition at line 252 of file player.cpp.

References file, last_pos, Response::POS, and Respond().

Referenced by End(), and Pos().

{
    assert(this->file != nullptr);

    this->file->SetPosition(pos);

    // This is required to make CanAnnounceTime() continue working.
    this->last_pos = pos / 1000 / 1000;

    this->Respond(0, Response(tag, Response::Code::POS)
                             .AddArg(std::to_string(pos)));
}

Quit()

Response Player::Quit

(

const std::string &

tag

)

Quits playd.

Parameters

tag	The tag of the request calling this command. For unsolicited quits, use Response::NOREQUEST.

Returns

Whether the quit succeeded.

Definition at line 210 of file player.cpp.

References dead, Eject(), Response::Failure(), MSG_CMD_PLAYER_CLOSING, and Response::Success().

{
    if (this->dead) return Response::Failure(tag, MSG_CMD_PLAYER_CLOSING);

    this->Eject(tag);
    this->dead = true;
    return Response::Success(tag);
}

Respond()

void Player::Respond ( int  id, Response  rs  ) const

private

Outputs a response, if there is a ResponseSink attached.

Otherwise, this method does nothing.

Parameters

id	The ID of the client receiving this response. Use 0 for broadcasts.
response	The Response to output.

Definition at line 290 of file player.cpp.

References io, and ResponseSink::Respond().

Referenced by Dump(), DumpState(), End(), PosRaw(), and Update().

{
    if (this->io != nullptr) this->io->Respond(id, rs);
}

SetIo()

void Player::SetIo

(

ResponseSink &

io

)

Sets the ResponseSink to which this Player shall send responses.

This sink shall be the target for WelcomeClient, as well as any responses generated by RunCommand or Update.

Parameters

io	The response sink (invariably the IO system).

Definition at line 36 of file player.cpp.

References io.

{
    this->io = &io;
}

SetPlaying()

Response Player::SetPlaying	(	const std::string &	tag,
		bool	playing
	)

Tells the audio file to start or stop playing.

Parameters

tag	The tag of the request calling this command. For unsolicited state changes, use Response::NOREQUEST.
playing	True if playing; false otherwise.

See also

Play

Stop

Definition at line 188 of file player.cpp.

References dead, DumpState(), Response::Failure(), file, Response::Invalid(), Error::Message(), MSG_CMD_PLAYER_CLOSING, Response::NOREQUEST, and Response::Success().

Referenced by End(), and Connection::RunCommand().

{
    if (this->dead) return Response::Failure(tag, MSG_CMD_PLAYER_CLOSING);

    // Why is SetPlaying not split between Start() and Stop()?, I hear the
    // best practices purists amongst you say.  Quite simply, there is a
    // large amount of fiddly exception boilerplate here that would
    // otherwise be duplicated between the two methods.

    assert(this->file != nullptr);

    try {
        this->file->SetPlaying(playing);
    } catch (NoAudioError &e) {
        return Response::Invalid(tag, e.Message());
    }

    this->DumpState(0, Response::NOREQUEST);

    return Response::Success(tag);
}

Update()

bool Player::Update

(

)

Instructs the Player to perform a cycle of work.

This includes decoding the next frame and responding to commands.

Returns

Whether the player has more cycles of work to do.

Definition at line 41 of file player.cpp.

References Audio::AT_END, CanAnnounceTime(), dead, End(), file, Response::NOREQUEST, Audio::PLAYING, Response::POS, and Respond().

Referenced by IoCore::UpdatePlayer().

{
    assert(this->file != nullptr);
    auto as = this->file->Update();

    if (as == Audio::State::AT_END) this->End(Response::NOREQUEST);
    if (as == Audio::State::PLAYING) {
        // Since the audio is currently playing, the position may have
        // advanced since last update.  So we need to update it.
        auto pos = this->file->Position();
        if (this->CanAnnounceTime(pos)) {
            this->Respond(0, Response(Response::NOREQUEST,
                                      Response::Code::POS)
                                     .AddArg(std::to_string(pos)));
        }
    }

    return !this->dead;
}

---

The documentation for this class was generated from the following files:

• src/player.hpp
• src/player.cpp