From a7dd849a8e4714efb1f304d2e872d1a7013200ab Mon Sep 17 00:00:00 2001 From: rwrozelle Date: Tue, 29 Jul 2025 13:00:47 -0400 Subject: [PATCH] Media player API enumeration alignment and feature flags (#9949) Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Co-authored-by: J. Nick Koston --- esphome/components/api/api.proto | 10 +++++ esphome/components/api/api_connection.cpp | 1 + esphome/components/api/api_pb2.cpp | 2 + esphome/components/api/api_pb2.h | 11 +++++- esphome/components/api/api_pb2_dump.cpp | 17 ++++++++ .../components/media_player/media_player.h | 39 ++++++++++++++++++- 6 files changed, 78 insertions(+), 2 deletions(-) diff --git a/esphome/components/api/api.proto b/esphome/components/api/api.proto index e0e1602fcb..4cf275c7f7 100644 --- a/esphome/components/api/api.proto +++ b/esphome/components/api/api.proto @@ -1297,6 +1297,7 @@ enum MediaPlayerState { MEDIA_PLAYER_STATE_IDLE = 1; MEDIA_PLAYER_STATE_PLAYING = 2; MEDIA_PLAYER_STATE_PAUSED = 3; + MEDIA_PLAYER_STATE_ANNOUNCING = 4; } enum MediaPlayerCommand { MEDIA_PLAYER_COMMAND_PLAY = 0; @@ -1304,6 +1305,13 @@ enum MediaPlayerCommand { MEDIA_PLAYER_COMMAND_STOP = 2; MEDIA_PLAYER_COMMAND_MUTE = 3; MEDIA_PLAYER_COMMAND_UNMUTE = 4; + MEDIA_PLAYER_COMMAND_TOGGLE = 5; + MEDIA_PLAYER_COMMAND_VOLUME_UP = 6; + MEDIA_PLAYER_COMMAND_VOLUME_DOWN = 7; + MEDIA_PLAYER_COMMAND_ENQUEUE = 8; + MEDIA_PLAYER_COMMAND_REPEAT_ONE = 9; + MEDIA_PLAYER_COMMAND_REPEAT_OFF = 10; + MEDIA_PLAYER_COMMAND_CLEAR_PLAYLIST = 11; } enum MediaPlayerFormatPurpose { MEDIA_PLAYER_FORMAT_PURPOSE_DEFAULT = 0; @@ -1338,6 +1346,8 @@ message ListEntitiesMediaPlayerResponse { repeated MediaPlayerSupportedFormat supported_formats = 9; uint32 device_id = 10 [(field_ifdef) = "USE_DEVICES"]; + + uint32 feature_flags = 11; } message MediaPlayerStateResponse { option (id) = 64; diff --git a/esphome/components/api/api_connection.cpp b/esphome/components/api/api_connection.cpp index cd27087fe8..6f71ab0929 100644 --- a/esphome/components/api/api_connection.cpp +++ b/esphome/components/api/api_connection.cpp @@ -1008,6 +1008,7 @@ uint16_t APIConnection::try_send_media_player_info(EntityBase *entity, APIConnec ListEntitiesMediaPlayerResponse msg; auto traits = media_player->get_traits(); msg.supports_pause = traits.get_supports_pause(); + msg.feature_flags = traits.get_feature_flags(); for (auto &supported_format : traits.get_supported_formats()) { msg.supported_formats.emplace_back(); auto &media_format = msg.supported_formats.back(); diff --git a/esphome/components/api/api_pb2.cpp b/esphome/components/api/api_pb2.cpp index f6f39f901f..35ba1e6c30 100644 --- a/esphome/components/api/api_pb2.cpp +++ b/esphome/components/api/api_pb2.cpp @@ -1725,6 +1725,7 @@ void ListEntitiesMediaPlayerResponse::encode(ProtoWriteBuffer buffer) const { #ifdef USE_DEVICES buffer.encode_uint32(10, this->device_id); #endif + buffer.encode_uint32(11, this->feature_flags); } void ListEntitiesMediaPlayerResponse::calculate_size(ProtoSize &size) const { size.add_length(1, this->object_id_ref_.size()); @@ -1740,6 +1741,7 @@ void ListEntitiesMediaPlayerResponse::calculate_size(ProtoSize &size) const { #ifdef USE_DEVICES size.add_uint32(1, this->device_id); #endif + size.add_uint32(1, this->feature_flags); } void MediaPlayerStateResponse::encode(ProtoWriteBuffer buffer) const { buffer.encode_fixed32(1, this->key); diff --git a/esphome/components/api/api_pb2.h b/esphome/components/api/api_pb2.h index f637e44df3..c994031bcb 100644 --- a/esphome/components/api/api_pb2.h +++ b/esphome/components/api/api_pb2.h @@ -149,6 +149,7 @@ enum MediaPlayerState : uint32_t { MEDIA_PLAYER_STATE_IDLE = 1, MEDIA_PLAYER_STATE_PLAYING = 2, MEDIA_PLAYER_STATE_PAUSED = 3, + MEDIA_PLAYER_STATE_ANNOUNCING = 4, }; enum MediaPlayerCommand : uint32_t { MEDIA_PLAYER_COMMAND_PLAY = 0, @@ -156,6 +157,13 @@ enum MediaPlayerCommand : uint32_t { MEDIA_PLAYER_COMMAND_STOP = 2, MEDIA_PLAYER_COMMAND_MUTE = 3, MEDIA_PLAYER_COMMAND_UNMUTE = 4, + MEDIA_PLAYER_COMMAND_TOGGLE = 5, + MEDIA_PLAYER_COMMAND_VOLUME_UP = 6, + MEDIA_PLAYER_COMMAND_VOLUME_DOWN = 7, + MEDIA_PLAYER_COMMAND_ENQUEUE = 8, + MEDIA_PLAYER_COMMAND_REPEAT_ONE = 9, + MEDIA_PLAYER_COMMAND_REPEAT_OFF = 10, + MEDIA_PLAYER_COMMAND_CLEAR_PLAYLIST = 11, }; enum MediaPlayerFormatPurpose : uint32_t { MEDIA_PLAYER_FORMAT_PURPOSE_DEFAULT = 0, @@ -1683,12 +1691,13 @@ class MediaPlayerSupportedFormat : public ProtoMessage { class ListEntitiesMediaPlayerResponse : public InfoResponseProtoMessage { public: static constexpr uint8_t MESSAGE_TYPE = 63; - static constexpr uint8_t ESTIMATED_SIZE = 76; + static constexpr uint8_t ESTIMATED_SIZE = 80; #ifdef HAS_PROTO_MESSAGE_DUMP const char *message_name() const override { return "list_entities_media_player_response"; } #endif bool supports_pause{false}; std::vector supported_formats{}; + uint32_t feature_flags{0}; void encode(ProtoWriteBuffer buffer) const override; void calculate_size(ProtoSize &size) const override; #ifdef HAS_PROTO_MESSAGE_DUMP diff --git a/esphome/components/api/api_pb2_dump.cpp b/esphome/components/api/api_pb2_dump.cpp index aca60464a3..5e17f6148a 100644 --- a/esphome/components/api/api_pb2_dump.cpp +++ b/esphome/components/api/api_pb2_dump.cpp @@ -383,6 +383,8 @@ template<> const char *proto_enum_to_string(enums::Medi return "MEDIA_PLAYER_STATE_PLAYING"; case enums::MEDIA_PLAYER_STATE_PAUSED: return "MEDIA_PLAYER_STATE_PAUSED"; + case enums::MEDIA_PLAYER_STATE_ANNOUNCING: + return "MEDIA_PLAYER_STATE_ANNOUNCING"; default: return "UNKNOWN"; } @@ -399,6 +401,20 @@ template<> const char *proto_enum_to_string(enums::Me return "MEDIA_PLAYER_COMMAND_MUTE"; case enums::MEDIA_PLAYER_COMMAND_UNMUTE: return "MEDIA_PLAYER_COMMAND_UNMUTE"; + case enums::MEDIA_PLAYER_COMMAND_TOGGLE: + return "MEDIA_PLAYER_COMMAND_TOGGLE"; + case enums::MEDIA_PLAYER_COMMAND_VOLUME_UP: + return "MEDIA_PLAYER_COMMAND_VOLUME_UP"; + case enums::MEDIA_PLAYER_COMMAND_VOLUME_DOWN: + return "MEDIA_PLAYER_COMMAND_VOLUME_DOWN"; + case enums::MEDIA_PLAYER_COMMAND_ENQUEUE: + return "MEDIA_PLAYER_COMMAND_ENQUEUE"; + case enums::MEDIA_PLAYER_COMMAND_REPEAT_ONE: + return "MEDIA_PLAYER_COMMAND_REPEAT_ONE"; + case enums::MEDIA_PLAYER_COMMAND_REPEAT_OFF: + return "MEDIA_PLAYER_COMMAND_REPEAT_OFF"; + case enums::MEDIA_PLAYER_COMMAND_CLEAR_PLAYLIST: + return "MEDIA_PLAYER_COMMAND_CLEAR_PLAYLIST"; default: return "UNKNOWN"; } @@ -1466,6 +1482,7 @@ void ListEntitiesMediaPlayerResponse::dump_to(std::string &out) const { #ifdef USE_DEVICES dump_field(out, "device_id", this->device_id); #endif + dump_field(out, "feature_flags", this->feature_flags); } void MediaPlayerStateResponse::dump_to(std::string &out) const { MessageDumpHelper helper(out, "MediaPlayerStateResponse"); diff --git a/esphome/components/media_player/media_player.h b/esphome/components/media_player/media_player.h index ee5889901c..98aa8f609d 100644 --- a/esphome/components/media_player/media_player.h +++ b/esphome/components/media_player/media_player.h @@ -6,12 +6,38 @@ namespace esphome { namespace media_player { +enum MediaPlayerEntityFeature : uint32_t { + PAUSE = 1 << 0, + SEEK = 1 << 1, + VOLUME_SET = 1 << 2, + VOLUME_MUTE = 1 << 3, + PREVIOUS_TRACK = 1 << 4, + NEXT_TRACK = 1 << 5, + + TURN_ON = 1 << 7, + TURN_OFF = 1 << 8, + PLAY_MEDIA = 1 << 9, + VOLUME_STEP = 1 << 10, + SELECT_SOURCE = 1 << 11, + STOP = 1 << 12, + CLEAR_PLAYLIST = 1 << 13, + PLAY = 1 << 14, + SHUFFLE_SET = 1 << 15, + SELECT_SOUND_MODE = 1 << 16, + BROWSE_MEDIA = 1 << 17, + REPEAT_SET = 1 << 18, + GROUPING = 1 << 19, + MEDIA_ANNOUNCE = 1 << 20, + MEDIA_ENQUEUE = 1 << 21, + SEARCH_MEDIA = 1 << 22, +}; + enum MediaPlayerState : uint8_t { MEDIA_PLAYER_STATE_NONE = 0, MEDIA_PLAYER_STATE_IDLE = 1, MEDIA_PLAYER_STATE_PLAYING = 2, MEDIA_PLAYER_STATE_PAUSED = 3, - MEDIA_PLAYER_STATE_ANNOUNCING = 4 + MEDIA_PLAYER_STATE_ANNOUNCING = 4, }; const char *media_player_state_to_string(MediaPlayerState state); @@ -56,6 +82,17 @@ class MediaPlayerTraits { std::vector &get_supported_formats() { return this->supported_formats_; } + uint32_t get_feature_flags() const { + uint32_t flags = 0; + flags |= MediaPlayerEntityFeature::PLAY_MEDIA | MediaPlayerEntityFeature::BROWSE_MEDIA | + MediaPlayerEntityFeature::STOP | MediaPlayerEntityFeature::VOLUME_SET | + MediaPlayerEntityFeature::VOLUME_MUTE | MediaPlayerEntityFeature::MEDIA_ANNOUNCE; + if (this->get_supports_pause()) { + flags |= MediaPlayerEntityFeature::PAUSE | MediaPlayerEntityFeature::PLAY; + } + return flags; + } + protected: bool supports_pause_{false}; std::vector supported_formats_{};