From f28a373898924ee6e0ca1b3053887313a32b29b5 Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Wed, 14 May 2025 11:48:54 +1200
Subject: [PATCH] [media_player] Deprecate ``MEDIA_PLAYER_SCHEMA`` (#8784)

---
 .../i2s_audio/media_player/__init__.py        | 19 ++++++-----
 esphome/components/media_player/__init__.py   | 34 ++++++++++++++++++-
 .../speaker/media_player/__init__.py          |  6 ++--
 3 files changed, 45 insertions(+), 14 deletions(-)

diff --git a/esphome/components/i2s_audio/media_player/__init__.py b/esphome/components/i2s_audio/media_player/__init__.py
index bed25b011f..51001e9444 100644
--- a/esphome/components/i2s_audio/media_player/__init__.py
+++ b/esphome/components/i2s_audio/media_player/__init__.py
@@ -2,7 +2,7 @@ from esphome import pins
 import esphome.codegen as cg
 from esphome.components import esp32, media_player
 import esphome.config_validation as cv
-from esphome.const import CONF_ID, CONF_MODE
+from esphome.const import CONF_MODE
 
 from .. import (
     CONF_I2S_AUDIO_ID,
@@ -57,16 +57,17 @@ def validate_esp32_variant(config):
 CONFIG_SCHEMA = cv.All(
     cv.typed_schema(
         {
-            "internal": media_player.MEDIA_PLAYER_SCHEMA.extend(
+            "internal": media_player.media_player_schema(I2SAudioMediaPlayer)
+            .extend(
                 {
-                    cv.GenerateID(): cv.declare_id(I2SAudioMediaPlayer),
                     cv.GenerateID(CONF_I2S_AUDIO_ID): cv.use_id(I2SAudioComponent),
                     cv.Required(CONF_MODE): cv.enum(INTERNAL_DAC_OPTIONS, lower=True),
                 }
-            ).extend(cv.COMPONENT_SCHEMA),
-            "external": media_player.MEDIA_PLAYER_SCHEMA.extend(
+            )
+            .extend(cv.COMPONENT_SCHEMA),
+            "external": media_player.media_player_schema(I2SAudioMediaPlayer)
+            .extend(
                 {
-                    cv.GenerateID(): cv.declare_id(I2SAudioMediaPlayer),
                     cv.GenerateID(CONF_I2S_AUDIO_ID): cv.use_id(I2SAudioComponent),
                     cv.Required(
                         CONF_I2S_DOUT_PIN
@@ -79,7 +80,8 @@ CONFIG_SCHEMA = cv.All(
                         *I2C_COMM_FMT_OPTIONS, lower=True
                     ),
                 }
-            ).extend(cv.COMPONENT_SCHEMA),
+            )
+            .extend(cv.COMPONENT_SCHEMA),
         },
         key=CONF_DAC_TYPE,
     ),
@@ -97,9 +99,8 @@ FINAL_VALIDATE_SCHEMA = _final_validate
 
 
 async def to_code(config):
-    var = cg.new_Pvariable(config[CONF_ID])
+    var = await media_player.new_media_player(config)
     await cg.register_component(var, config)
-    await media_player.register_media_player(var, config)
 
     await cg.register_parented(var, config[CONF_I2S_AUDIO_ID])
 
diff --git a/esphome/components/media_player/__init__.py b/esphome/components/media_player/__init__.py
index 14fe1fdb6a..2f5fe0c03e 100644
--- a/esphome/components/media_player/__init__.py
+++ b/esphome/components/media_player/__init__.py
@@ -2,6 +2,8 @@ from esphome import automation
 import esphome.codegen as cg
 import esphome.config_validation as cv
 from esphome.const import (
+    CONF_ENTITY_CATEGORY,
+    CONF_ICON,
     CONF_ID,
     CONF_ON_IDLE,
     CONF_ON_STATE,
@@ -10,6 +12,7 @@ from esphome.const import (
 )
 from esphome.core import CORE
 from esphome.coroutine import coroutine_with_priority
+from esphome.cpp_generator import MockObjClass
 from esphome.cpp_helpers import setup_entity
 
 CODEOWNERS = ["@jesserockz"]
@@ -103,7 +106,13 @@ async def register_media_player(var, config):
     await setup_media_player_core_(var, config)
 
 
-MEDIA_PLAYER_SCHEMA = cv.ENTITY_BASE_SCHEMA.extend(
+async def new_media_player(config, *args):
+    var = cg.new_Pvariable(config[CONF_ID], *args)
+    await register_media_player(var, config)
+    return var
+
+
+_MEDIA_PLAYER_SCHEMA = cv.ENTITY_BASE_SCHEMA.extend(
     {
         cv.Optional(CONF_ON_STATE): automation.validate_automation(
             {
@@ -134,6 +143,29 @@ MEDIA_PLAYER_SCHEMA = cv.ENTITY_BASE_SCHEMA.extend(
 )
 
 
+def media_player_schema(
+    class_: MockObjClass,
+    *,
+    entity_category: str = cv.UNDEFINED,
+    icon: str = cv.UNDEFINED,
+) -> cv.Schema:
+    schema = {cv.GenerateID(CONF_ID): cv.declare_id(class_)}
+
+    for key, default, validator in [
+        (CONF_ENTITY_CATEGORY, entity_category, cv.entity_category),
+        (CONF_ICON, icon, cv.icon),
+    ]:
+        if default is not cv.UNDEFINED:
+            schema[cv.Optional(key, default=default)] = validator
+
+    return _MEDIA_PLAYER_SCHEMA.extend(schema)
+
+
+# Remove before 2025.11.0
+MEDIA_PLAYER_SCHEMA = media_player_schema(MediaPlayer)
+MEDIA_PLAYER_SCHEMA.add_extra(cv.deprecated_schema_constant("media_player"))
+
+
 MEDIA_PLAYER_ACTION_SCHEMA = automation.maybe_simple_id(
     cv.Schema(
         {
diff --git a/esphome/components/speaker/media_player/__init__.py b/esphome/components/speaker/media_player/__init__.py
index 35d763b1f8..cedafe214d 100644
--- a/esphome/components/speaker/media_player/__init__.py
+++ b/esphome/components/speaker/media_player/__init__.py
@@ -271,9 +271,8 @@ PIPELINE_SCHEMA = cv.Schema(
 )
 
 CONFIG_SCHEMA = cv.All(
-    media_player.MEDIA_PLAYER_SCHEMA.extend(
+    media_player.media_player_schema(SpeakerMediaPlayer).extend(
         {
-            cv.GenerateID(): cv.declare_id(SpeakerMediaPlayer),
             cv.Required(CONF_ANNOUNCEMENT_PIPELINE): PIPELINE_SCHEMA,
             cv.Optional(CONF_MEDIA_PIPELINE): PIPELINE_SCHEMA,
             cv.Optional(CONF_BUFFER_SIZE, default=1000000): cv.int_range(
@@ -343,9 +342,8 @@ async def to_code(config):
         # Allocate wifi buffers in PSRAM
         esp32.add_idf_sdkconfig_option("CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP", True)
 
-    var = cg.new_Pvariable(config[CONF_ID])
+    var = await media_player.new_media_player(config)
     await cg.register_component(var, config)
-    await media_player.register_media_player(var, config)
 
     cg.add_define("USE_OTA_STATE_CALLBACK")