{"id":129802,"date":"2021-05-10T12:00:49","date_gmt":"2021-05-10T12:00:49","guid":{"rendered":"https:\/\/developer.apple.com\/news\/?id=33cpm46r"},"modified":"2021-05-10T12:00:49","modified_gmt":"2021-05-10T12:00:49","slug":"support-directional-remotes-in-your-tvos-app","status":"publish","type":"post","link":"https:\/\/sickgaming.net\/blog\/2021\/05\/10\/support-directional-remotes-in-your-tvos-app\/","title":{"rendered":"Support directional remotes in your tvOS app"},"content":{"rendered":"
\"A<\/div>\n

In addition to the Siri Remote, tvOS provides support for a variety of hardware and software remotes with touch or button interfaces. When your app uses standard frameworks \u2014 like UIKit and AVKit \u2014 tvOS will automatically handle remote interactions to provide a consistent and familiar experience. If you have an app that includes custom interface elements or media players, you can still easily support navigation and content-based features for hardware and software remotes with both touch and button interfaces. Here\u2019s how.<\/p>\n

<\/div>\n

Explore app navigation<\/h3>\n

On Apple TV, people use a remote or game controller to navigate through interface elements like content posters, apps, or buttons, highlighting each item as they come to it. The highlighted item is said to be focused<\/em> or in focus<\/em>. The focus engine in UIKit controls focus and movement on tvOS, listens for incoming focus-movement events triggered from a remote or game controller, and notifies your app so you can provide the appropriate experience. All standard gestures in tvOS work with directional remotes by default, and you can also provide support in your app for custom gestures with classes like UITapGestureRecognizer<\/code>.<\/p>\n

About focus interactions for Apple TV<\/a><\/p>\n

Adapt custom gestures for directional remotes<\/strong>
\nIf you support custom gestures that control special actions within your app\u2019s interface, you can add UITapGestureRecognizer<\/code> to map to an explicit directional event.<\/p>\n

\nlet<\/span> customGesture =<\/span> UITapGestureRecognizer<\/span>(target: self<\/span>, action: #selector<\/span>(specialAction))\ncustomGesture.allowedPressTypes =<\/span> [.downArrow]\nview.addGestureRecognizer(customGesture)<\/code><\/pre>\n
Learn more about detecting gestures and button presses<\/a><\/p>\n
Explore the App Programming Guide for tvOS<\/a><\/p>\n
Support remotes with dedicated channel and guide buttons<\/strong>
\nSome Apple TV-compatible remotes offer dedicated guide buttons and up and down arrows to control channel changes and electronic programming guide paging functionality. If your app includes channels or a programming guide, you can support these interactions on remotes with dedicated buttons through the TV Services framework.<\/p>\n
Providing Channel Navigation<\/a><\/p>\n
Support playback interactions in a custom video player<\/h3>\n
If your app includes video content, you can use AVPlayerViewController<\/code> to provide the best experience across all remote types. If you\u2019ve created a custom video player, however, you can use UITapGestureRecognizer<\/code> map specific remote buttons to playback interactions as well as MPRemoteCommandCenter<\/code> to handle media player events.<\/p>\n
MPRemoteCommandCenter<\/a><\/p>\n
Becoming a Now Playable App<\/a><\/p>\n
Remote Command Center Events<\/a><\/p>\n
Play and pause<\/strong>
\nWhen someone plays content in your app, pressing select, play, pause or play\/pause should update the playback state and display the player transport bar. You\u2019ll need to use UITapGestureRecognizer<\/code> and MPRemoteCommandCenter<\/code> to handle these interactions in your custom player.<\/p>\n
\nlet<\/span> playPauseGesture =<\/span> UITapGestureRecognizer<\/span>(target: self<\/span>, action: #selector<\/span>(togglePlaybackState)\nplayPauseGesture.allowedPressTypes =<\/span> [.playPause, .select]\nview.addGestureRecognizer(playPauseGesture) let<\/span> remoteCommandCenter =<\/span> MPRemoteCommandCenter<\/span>.shared()\nremoteCommandCenter.playCommand.addTarget(self<\/span>, action: #selector<\/span>(playHandler))\nremoteCommandCenter.pauseCommand.addTarget(self<\/span>, action: #selector<\/span>(pauseHandler))<\/code><\/pre>\n
Skip forward and skip backward<\/strong>
\nWhen using a directional remote, people can skip through video in the appropriate direction by pressing left or right on the directional pad. Additionally, certain remotes have dedicated skip forward and skip backward buttons that can map to this functionality. To ensure someone can navigate forward and backward through your content, use UITapGestureRecognizer<\/code> and MPRemoteCommandCenter<\/code> to create the correct gestures.<\/p>\n
\nlet<\/span> dPadLeftGesture =<\/span> UITapGestureRecognizer<\/span>(target: self<\/span>, action: #selector<\/span>(dPadLeftHandler))\ndPadLeftGesture.allowedPressTypes =<\/span> [NSNumber<\/span>(value: UIPress<\/span>.PressType<\/span>.leftArrow.rawValue)]\nview.addGestureRecognizer(dPadLeftGesture) let<\/span> dPadRightGesture =<\/span> UITapGestureRecognizer<\/span>(target: self<\/span>, action: #selector<\/span>(dPadRightHandler))\ndPadRightGesture.allowedPressTypes =<\/span> [NSNumber<\/span>(value: UIPress<\/span>.PressType<\/span>.rightArrow.rawValue)]\nview.addGestureRecognizer(dPadRightGesture) let<\/span> remoteCommandCenter =<\/span> MPRemoteCommandCenter<\/span>.shared()\nremoteCommandCenter.skipForwardCommand.addTarget(self<\/span>, action: #selector<\/span>(skipForwardHandler))\nremoteCommandCenter.skipBackwardCommand.addTarget(self<\/span>, action: #selector<\/span>(skipBackwardHandler))<\/code><\/pre>\n
Fast forward and rewind<\/strong>
\nPeople can fast forward and rewind through content in different ways depending on the remote they use. Some remotes offer dedicated fast forward and rewind buttons, while others achieve this with a long press on the left or right directional pad buttons.<\/p>\n
\n
Note: On tvOS, we recommend using the following UI labels to pair with the corresponding supported player rates.<\/em><\/p>\n
UI Labels to tvOS Playback Rates<\/strong>
\n1x = 8.0<\/em>
\n2x = 24.0<\/em>
\n3x = 48.0<\/em>
\n4x = 96.0<\/em><\/p>\n
\n
Dedicated fast forward and rewind buttons<\/strong>
\nFor remotes with dedicated fast forward and rewind buttons, a short press will initiate a continuous seek forward or backward. Each subsequent press of that button will increase the seek rate. Once someone passes the last seek rate, the player returns to its normal playback rate. If the opposite button is pressed while seeking, it decreases the seek rate; each subsequent press will do the same until the player returns to its normal playback rate. <\/p>\n
You can support these controls in your app with changePlaybackRateCommand<\/code> in MPRemoteCommandCenter<\/code>. You\u2019ll also want to make sure to update your player rate with the playbackRate<\/code> property of the MPChangePlaybackRateCommandEvent<\/code>.<\/p>\n
If someone holds a dedicated fast forward or rewind button, MPRemoteCommandCenter<\/code> will fire a seekForwardCommand<\/code> or seekBackwardCommand<\/code>. Your registered target will receive MPSeekCommandEventType.beginSeeking<\/code>, and your app should set the player to the desired seek rate. Once someone releases the button, your app receives a new command event with the case MPSeekCommandEventType.endSeeking<\/code>, telling it to return the player rate to normal.<\/p>\n
Directional pad fast forward and rewind<\/strong>
\nIf a person long presses the left or right directional pad buttons, your app should seek forward or backward respectively and update the seek rate. While seeking, a person can use a short press on the left or right directional pad buttons to update the seek rate as described in the previous section.<\/p>\n
Adopt fast forward and rewind in your custom video player<\/strong>
\nTo incorporate these gestures in your app for all remotes, you\u2019ll want to use MPRemoteCommandCenter<\/code>, UITapGestureRecognizer<\/code> and UILongPressGestureRecognizer<\/code>.<\/p>\n
\/\/ MPRemoteCommands to handle dedicated fast forward and rewind buttons\nlet remoteCommandCenter = MPRemoteCommandCenter.shared() \/\/ MPRemoteCommands to handle dedicated fast forward and rewind (short presses)\nremoteCommandCenter.changePlaybackRateCommand.addTarget { [unowned self] event in guard let event = event as? MPChangePlaybackRateCommandEvent else { return .commandFailed } self.assetPlayer.player.rate = event.playbackRate return .success\n} \/\/ MPRemoteCommands to handle dedicated fast forward button (long press)\nremoteCommandCenter.seekForwardCommand.addTarget { [unowned self] event in guard let event = event as? MPSeekCommandEvent else { return .commandFailed } if event.type == .beginSeeking { self.assetPlayer.player.rate = 24.0 } if event.type == .endSeeking { self.assetPlayer.player.rate = 1.0 } return .success\n} \/\/ MPRemoteCommands to handle dedicated rewind button (long press)\nremoteCommandCenter.seekBackwardCommand.addTarget { [unowned self] event in guard let event = event as? MPSeekCommandEvent else { return .commandFailed } if event.type == .beginSeeking { self.assetPlayer.player.rate = -24.0 } if event.type == .endSeeking { self.assetPlayer.player.rate = 1.0 } return .success\n} \/\/ Gestures to handle fast forward and rewind from directional pad \/\/ Gesture to handle dpad right (long press)\nlet dPadRightLong = UILongPressGestureRecognizer(target: self, action: #selector(dPadRightLongHandler))\ndPadRightLong.allowedPressTypes = [NSNumber(value: UIPress.PressType.rightArrow.rawValue)]\nview.addGestureRecognizer(dPadRightLong) \/\/ Gesture to handle dpad left (long press)\nlet dPadLeftLong = UILongPressGestureRecognizer(target: self, action: #selector(dPadLeftLongHandler))\ndPadLeftLong.allowedPressTypes = [NSNumber(value: UIPress.PressType.leftArrow.rawValue)]\nview.addGestureRecognizer(dPadLeftLong) \/\/ Gesture to handle dpad right (short press)\nlet dPadRightGesture = UITapGestureRecognizer(target: self, action: #selector(dPadRightHandler))\ndPadRightGesture.allowedPressTypes = [NSNumber(value: UIPress.PressType.rightArrow.rawValue)]\nview.addGestureRecognizer(dPadRightGesture) \/\/ Gesture to handle dpad left (short press)\nlet dPadLeftGesture = UITapGestureRecognizer(target: self, action: #selector(dPadLeftHandler))\ndPadLeftGesture.allowedPressTypes = [NSNumber(value: UIPress.PressType.leftArrow.rawValue)]\nview.addGestureRecognizer(dPadLeftGesture)<\/code><\/pre>\n
Support additional interactions in a custom player<\/h3>\n
People expect up or down swipes or presses to provide a consistent experience during video playback, like showing the player controls and transport bar on a press or swipe up, or showing the information panel on a swipe or press down.<\/p>\n
Transport Bar<\/strong>
\nPeople should be able to see how much time remains on a piece of content. Swiping up or pressing up on a directional pad should show the player\u2019s transport bar without stopping or pausing the player.<\/p>\n
\nlet<\/span> upGesture =<\/span> UITapGestureRecognizer<\/span>(target: self<\/span>, action: .upGestureRecognizer)\nupGesture.allowedPressTypes =<\/span> [.upArrow]\nview.addGestureRecognizer(upGesture)<\/code><\/pre>\n
Information Panel<\/strong>
\nPeople should be able to access subtitle and audio selections along with other options while viewing content. Swiping down or pressing down on a directional pad should show these options without stopping or pausing the player.<\/p>\n
\nlet<\/span> downGesture =<\/span> UITapGestureRecognizer<\/span>(target: self<\/span>, action: .downGestureRecognizer)\ndownGesture.allowedPressTypes =<\/span> [.downArrow]\nview.addGestureRecognizer(downGesture)<\/code><\/pre>\n
Putting Your Users In Control<\/strong>
\nNo matter which interaction method someone chooses to use with Apple TV, you can ensure they remain in control by offering a great experience in your app for all remotes. It\u2019s easy when you use system frameworks like AVFoundation and AVKit and support custom gestures and media interactions with UITapGestureRecognizer<\/code> and MPRemoteCommandCenter<\/code>. And when you do, it lets people enjoy your content without worrying how to interact with your app.<\/p>\n","protected":false},"excerpt":{"rendered":"
In addition to the Siri Remote, tvOS provides support for a variety of hardware and software remotes with touch or button interfaces. When your app uses standard frameworks \u2014 like UIKit and AVKit \u2014 tvOS will automatically handle remote interactions to provide a consistent and familiar experience. If you have an app that includes custom […]<\/p>\n","protected":false},"author":2,"featured_media":129803,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[55],"tags":[],"class_list":["post-129802","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-apple-developer-news"],"_links":{"self":[{"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/posts\/129802","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/comments?post=129802"}],"version-history":[{"count":0,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/posts\/129802\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/media\/129803"}],"wp:attachment":[{"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/media?parent=129802"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/categories?post=129802"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/sickgaming.net\/blog\/wp-json\/wp\/v2\/tags?post=129802"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
UITapGestureRecognizer<\/a><\/p>\n