constcontext=cast.framework.CastReceiverContext.getInstance();constplayerManager=context.getPlayerManager();playerManager.setMessageInterceptor(cast.framework.messages.MessageType.LOAD,loadRequestData=>{loadRequestData.media.metadata=newcast.framework.messages.MusicTrackMediaMetadata();// Set image on secondaryImage field of metadata objectloadRequestData.media.metadata.secondaryImage=newcast.framework.messages.Image('https://www.image.png');returnloadRequestData;});
// To unset the secondary image, set secondaryImage to null.letmediaInformation=playerManager.getMediaInformation();mediaInformation.metadata.secondaryImage=null;playerManager.setMediaInformation(mediaInformation);
/** * Sets the image url for the secondary image overlay. Replaces any image that * was previously set. */castUiManager.setSecondaryImage(cast.framework.ui.SecondaryImagePosition.TOP_RIGHT_VIDEO_OVERLAY,'http://www.image.png');
如要移除次要圖片，請將圖片網址設為 null 或
空字串。
// To clear out the image, set the url to null or an empty string.constcastUiManager=cast.framework.ui.UiManager.getInstance();castUiManager.setSecondaryImage(cast.framework.ui.SecondaryImagePosition.TOP_RIGHT_VIDEO_OVERLAY,null);
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-07-25 (世界標準時間)。"],[[["\u003cp\u003eCast developers can display a secondary image alongside audio and video content on supported devices to provide additional context.\u003c/p\u003e\n"],["\u003cp\u003eFor audio content, the secondary image is managed through metadata using the \u003ccode\u003esecondaryImage\u003c/code\u003e property within \u003ccode\u003eMusicTrackMediaMetadata\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eFor video content, the \u003ccode\u003eUiManager\u003c/code\u003e and its \u003ccode\u003esetSecondaryImage\u003c/code\u003e method control the display and removal of the secondary image.\u003c/p\u003e\n"],["\u003cp\u003eThe secondary image feature is only available when using the default UI provided by the Web Receiver's \u003ccode\u003e<cast-media-player>\u003c/code\u003e element for audio content.\u003c/p\u003e\n"],["\u003cp\u003eThis feature is supported on various devices like Chromecast, Chromecast with Google TV, and Smart Displays, with minor differences in implementation between audio and video content.\u003c/p\u003e\n"]]],[],null,["# Secondary Image\n\nCast developers can add an informational (secondary) image to the UI for audio\nand video applications. View the supported\n[image formats](/cast/docs/media#image_formats) for compatibility.\n\nThe secondary image appears on the top right of the display, and can be used to\nshow a graphic with additional information about the currently-playing content,\nsuch as the content format, the radio station call sign, or the TV-show rating.\nThe secondary image persists on screen as long as the feature is enabled for the\ncurrent content and the player is not in an idle state.\n\n[Table 1](#table-1) shows a user's experience when the feature is\nenabled on the applicable device types and controls. Details of implementation\nand integration differ slightly between audio and video apps. See the sections\nbelow for integrating this feature in your Web Receiver app.\n\n| Device Type | Audio Content | Video Content |\n|------------------------------|---------------|------------------------------------------------------------------------------|\n| Chromecast | | |\n| Chromecast w/Google TV | | |\n| Smart Display | | |\n| Smart Display Remote Control | | Note: Secondary image is not supported on remote controls for video content. |\n[*Table 1: Secondary image UI by content and device type*]\n\nAudio\n-----\n\n### Overview\n\nThe secondary image for audio content is driven by the metadata of the loaded\ncontent. Once the media item is loaded, any subsequent changes to the metadata's\n`secondaryImage` property are reflected in the UI.\n\nIf a smart display is used as a remote control for audio, the secondary image\nwill also appear on the smart display's UI when set.\n| **Note:** We encourage Cast developers to utilize the default audio UI provided through the Web Receiver's `\u003ccast-media-player\u003e` element. Using the default UI provides a consistent user experience across Chromecast, smart displays, and Chromecast with Google TV, with minimal overhead. The secondary image feature is not supported for apps using custom UI. This does not apply to remote controls as they will always display the secondary image when set.\n\n### Implementation\n\nTo set, remove, or update the secondary image, the\n[`secondaryImage`](/cast/docs/reference/web_receiver/cast.framework.messages.MusicTrackMediaMetadata#secondaryImage)\nproperty of `MusicTrackMediaMetadata` needs to be modified. The property takes\nan [`Image`](/cast/docs/reference/web_receiver/cast.framework.messages.Image)\nobject populated with the URL describing where the secondary image is hosted.\n\nIn the sample below, the secondary image is set in the `load` interceptor. When\nthe player finishes loading the content, the secondary image is displayed. \n\n const context = cast.framework.CastReceiverContext.getInstance();\n const playerManager = context.getPlayerManager();\n playerManager.setMessageInterceptor(\n cast.framework.messages.MessageType.LOAD, loadRequestData =\u003e {\n loadRequestData.media.metadata =\n new cast.framework.messages.MusicTrackMediaMetadata();\n\n // Set image on secondaryImage field of metadata object\n loadRequestData.media.metadata.secondaryImage =\n new cast.framework.messages.Image('https://www.image.png');\n\n return loadRequestData;\n });\n\nTo update the secondary image during playback, the application should use\n`PlayerManager` to obtain the `MediaInformation` by calling\n[`getMediaInformation`](/cast/docs/reference/web_receiver/cast.framework.PlayerManager#getMediaInformation).\nThe application should then modify the `metadata` by updating the\n`secondaryImage` property to the desired value. Finally,\ncalling[`setMediaInformation`](/cast/docs/reference/web_receiver/cast.framework.PlayerManager#setMediaInformation)\nwith the new information will update the UI. This method can be used to handle\nchanges in metadata provided through updates such as `EMSG` or `ID3` events\nduring playback. \n\n const context = cast.framework.CastReceiverContext.getInstance();\n const playerManager = context.getPlayerManager();\n playerManager.addEventListener(cast.framework.events.EventType.EMSG, () =\u003e {\n let mediaInformation = playerManager.getMediaInformation();\n mediaInformation.metadata.secondaryImage =\n new cast.framework.messages.Image('http://anotherimage.png');\n playerManager.setMediaInformation(mediaInformation);\n });\n\nTo unset the secondary image, set the `secondaryImage` property to null on the\nmetadata object. \n\n // To unset the secondary image, set secondaryImage to null.\n let mediaInformation = playerManager.getMediaInformation();\n mediaInformation.metadata.secondaryImage = null;\n playerManager.setMediaInformation(mediaInformation);\n\nVideo\n-----\n\n### Overview\n\nFor video content, the secondary image is set and removed using\n[`UiManager`](/cast/docs/reference/web_receiver/cast.framework.ui.UiManager).\nThe secondary image is shown with the video controls overlay.\n\n### Implementation\n\nTo set the secondary image, the application must get an instance of `UiManager`\nand call\n[`setSecondaryImage`](/cast/docs/reference/web_receiver/cast.framework.ui.UiManager#setSecondaryImage).\nIt takes two parameters: the\n[`SecondaryImagePosition`](/cast/docs/reference/web_receiver/cast.framework.ui#.SecondaryImagePosition)\nand the url of the image. Setting the secondary image can be done at anytime but\nwill only be shown when a user triggers the overlay to be foregrounded. \n\n /**\n * Sets the image url for the secondary image overlay. Replaces any image that\n * was previously set.\n */\n castUiManager.setSecondaryImage(\n cast.framework.ui.SecondaryImagePosition.TOP_RIGHT_VIDEO_OVERLAY,\n 'http://www.image.png');\n\nRemoving the secondary image is done by setting the image url to `null` or an\nempty string. \n\n // To clear out the image, set the url to null or an empty string.\n const castUiManager = cast.framework.ui.UiManager.getInstance();\n castUiManager.setSecondaryImage(\n cast.framework.ui.SecondaryImagePosition.TOP_RIGHT_VIDEO_OVERLAY, null);\n\nNext steps\n----------\n\nThis concludes the features that you can add to your Web Receiver. You can now\nbuild a sender app on [iOS](/cast/docs/ios_sender),\n[Android](/cast/docs/android_sender), or [Web](/cast/docs/web_sender)."]]
