@techwavedev/agi-agent-kit 1.5.3 → 1.6.0

package/templates/skills/extended/other/hig-patterns/references/playing-audio.md

@@ -0,0 +1,124 @@
+---
+title: "Playing audio | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/playing-audio
+
+# Playing audio
+
+People expect rich audio experiences that automatically adjust when the context changes on the device.
+
+![A sketch of a speaker emitting sound waves, suggesting the playback of audio. The image is overlaid with rectangular and circular grid lines and is tinted orange to subtly reflect the orange in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/1cf1272e2d6283fc614294242efe2145/patterns-playing-audio-intro%402x.png)
+
+Devices can play audio in a variety of ways, such as through internal or external speakers, headphones, and wirelessly through devices that use Bluetooth or AirPlay. To manipulate sound on their devices people use several types of controls, including volume buttons, the Ring/Silent switch on iPhone, headphone controls, the Control Center volume slider, and sound controls in third-party accessories. Whether sound is a primary part of your experience or an embellishment, you need to make sure it behaves as people expect as they make changes to volume and output.
+
+**Silence.** People switch a device to silent when they want to avoid being interrupted by unexpected sounds like ringtones and incoming message tones. In this scenario, they also want to silence nonessential sounds, such as keyboard clicks, sound effects, game soundtracks, and other audible feedback. When a device is in silent mode, it plays only the audio that people explicitly initiate, like media playback, alarms, and audio/video messaging.
+
+**Volume.** People expect their volume settings to affect all sound in the system — including music and in-app sound effects — regardless of the method they use to adjust the volume. An exception is the ringer volume on iPhone, which people can adjust separately in Settings.
+
+**Headphones.** People use headphones to keep their listening private and in some cases to free their hands. When connecting headphones, people expect sound to reroute automatically without interruption; when disconnecting headphones, they expect playback to pause immediately.
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/playing-audio#Best-practices)
+
+**Adjust levels automatically when necessary — don’t adjust the overall volume.** Your app can adjust relative, independent volume levels to achieve a great mix of audio, but the system volume always governs the final output.
+
+**Permit rerouting of audio when possible.** People often want to select a different audio output device. For example, they may want to listen to music through their living room stereo, car radio, or Apple TV. Support this capability unless there’s a compelling reason not to.
+
+**Use the system-provided volume view to let people make audio adjustments.** The volume view includes a volume-level slider and a control for rerouting audio output. You can customize the appearance of the slider. For developer guidance, see [`MPVolumeView`](https://developer.apple.com/documentation/MediaPlayer/MPVolumeView).
+
+**Choose an audio category that fits the way your app or game uses sound.** Depending on the audio category you choose, your app’s sounds can mix with other audio, play while your app is in the background, or stop when people set the Ring/Silent switch to silent. As much as possible, pick a category that helps your app meet people’s expectations. For example, don’t make people stop listening to music from another app if you don’t need to. For developer guidance, see [`AVAudioSession.Category`](https://developer.apple.com/documentation/AVFAudio/AVAudioSession/Category-swift.struct).
+
+Category| Meaning| Behavior  
+---|---|---  
+Solo ambient| Sound isn’t essential, but it silences other audio. For example, a game with a soundtrack.| Responds to the silence switch. Doesn’t mix with other sounds. Doesn’t play in the background.  
+Ambient| Sound isn’t essential, and it doesn’t silence other audio. For example, a game that lets people play music from another app during gameplay in place of the game’s soundtrack.| Responds to the silence switch. Mixes with other sounds. Doesn’t play in the background.  
+Playback| Sound is essential and might mix with other audio. For example, an audiobook or educational app that teaches a foreign language, which people might want to listen to after leaving the app.| Doesn’t respond to the silence switch. May or may not mix with other sounds. Can play in the background.  
+Record| Sound is recorded. For example, a note-taking app that offers an audio recording mode. An app of this nature might switch its category to playback if it lets people play the recorded notes.| Doesn’t respond to the silence switch. Doesn’t mix with other sounds. Can record in the background.  
+Play and record| Sound is recorded and played, potentially simultaneously. For example, an audio messaging or video calling app.| Doesn’t respond to the silence switch. May or may not mix with other sounds. Can record and play in the background.  
+  
+**Respond to audio controls only when it makes sense.** People can control audio playback from outside your app’s interface — such as in Control Center or with controls on their headphones — regardless of whether your app is in the foreground or background. If your app is actively playing audio, in a clear audio-related context, or connected to a device that uses Bluetooth or AirPlay, it’s fine to respond to audio controls. Otherwise, when people activate a control, avoid halting audio currently playing from another app.
+
+**Avoid repurposing audio controls.** People expect audio controls to behave consistently in all apps, so it’s essential to avoid redefining the meaning of an audio control in your app. If your app doesn’t support certain controls, don’t respond to them.
+
+**Consider creating custom audio player controls only if you need to offer commands that the system doesn’t support.** For example, you might want to define custom increments for skipping forward or backward, or present content that’s related to the playing audio, such as a sports score.
+
+**Let other apps know when your app finishes playing temporary audio.** If your app can temporarily interrupt the audio of other apps, be sure to flag your audio session in a way that lets other apps know when they can resume. For developer guidance, see [`notifyOthersOnDeactivation`](https://developer.apple.com/documentation/AVFAudio/AVAudioSession/SetActiveOptions/notifyOthersOnDeactivation).
+
+## [Handling interruptions](https://developer.apple.com/design/human-interface-guidelines/playing-audio#Handling-interruptions)
+
+Although most apps and games rely on the system’s default interruption behavior, you can customize this behavior to better accommodate your needs.
+
+**Determine how to respond to audio-session interruptions.** For example, if your app supports recording or other audio-related tasks that people don’t want interrupted, you can tell the system to avoid interrupting the currently playing audio for an incoming call unless people choose to accept it. Another example is a VoIP app, which must end a call when people close the Smart Folio of their iPad while they’re using the built-in microphone. Closing the Smart Folio automatically mutes the iPad microphone and by default interrupts the audio session associated with it. If a VoIP app restarts the audio session when people reopen their Smart Folio, it risks invading people’s privacy by unmuting the microphone without their knowledge. You can inspect an audio-session interruption to help determine the right way to respond; for developer guidance, see [Handling audio interruptions](https://developer.apple.com/documentation/AVFAudio/handling-audio-interruptions).
+
+**When an interruption ends, determine whether to resume audio playback automatically.** Sometimes, audio from a different app can interrupt the audio your app is playing. An interruption can be _resumable_ , like an incoming phone call, or _nonresumable_ , like when people start a new music playlist. Use the interruption type and your app’s type to decide whether to resume playback automatically. For example, a media playback app that’s actively playing audio when an interruption occurs can check to be sure the type is resumable before continuing playback when the interruption ends. On the other hand, a game doesn’t need to check the interruption type before automatically resuming playback, because a game plays audio without an explicit user choice. For developer guidance, see [`shouldResume`](https://developer.apple.com/documentation/AVFAudio/AVAudioSession/InterruptionOptions/shouldResume).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/playing-audio#Platform-considerations)
+
+### [iOS, iPadOS](https://developer.apple.com/design/human-interface-guidelines/playing-audio#iOS-iPadOS)
+
+**Use the system’s sound services to play short sounds and vibrations.** For developer guidance, see [Audio Services](https://developer.apple.com/documentation/AudioToolbox/audio-services).
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/playing-audio#macOS)
+
+In macOS, notification sounds mix with other audio by default.
+
+### [tvOS](https://developer.apple.com/design/human-interface-guidelines/playing-audio#tvOS)
+
+In tvOS, the system plays audio only when people initiate it, through interactions within apps and games or when performing device calibrations. For example, tvOS doesn’t play sounds to accompany components like alerts or notifications.
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/playing-audio#visionOS)
+
+Subtle, expressive sounds are everywhere in visionOS, enhancing experiences and providing essential feedback when people look at a virtual object and use gestures to interact with it. The system combines audio algorithms with information about a person’s physical surroundings to produce _Spatial Audio_ , which is sound that people can perceive as coming from specific locations in space, not just from speakers.
+
+Important
+
+In visionOS, as in every platform, avoid communicating important information using only sound. Always provide additional ways to help people understand your app. For guidance, see [Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility).
+
+In visionOS, audio playback from the Now Playing app pauses automatically when people close the app’s window, and audio from an app that isn’t the Now Playing app can duck when people look away from it to different app.
+
+**Prefer playing sound.** People generally choose to keep sounds audible while they’re wearing the device, so an app that doesn’t play sound — especially in an immersive moment — can feel lifeless and may even seem broken. Throughout the design process, look for opportunities to create meaningful sounds that aid navigation and help people understand the spatial qualities of your app.
+
+**Design custom sounds for custom UI elements.** In general, a system-provided element plays sound to help people locate it and receive feedback when they interact with it. To help people interact with your custom elements, design sounds that provide feedback and enhance the spatial experience of your app.
+
+**Use Spatial Audio to create an intuitive, engaging experience.** Because people can perceive Spatial Audio as coming from anywhere around them, it works especially well in a fully immersive context as a way to help an experience feel lifelike. _Ambient audio_ provides pervasive sounds that can help anchor people in a virtual world and an _audio source_ can sound like it comes from a specific object. As you build the soundscape for your app, consider using both types of audio.
+
+**Consider defining a range of places from which your app sounds can originate.** Spatial Audio helps people locate the object that’s making sound, whether it’s stationary or moving in space. For example, when people move an app window that’s playing audio, the sound continues to come directly from the window, wherever people move it.
+
+**Consider varying sounds that people could perceive as repetitive over time.** For example, the system subtly varies the pitch and volume of the virtual keyboard’s sounds, suggesting the different sounds a physical keyboard can make as people naturally vary the speed and forcefulness of their typing. An efficient way to achieve a pleasing variation in sound is to randomize a sound file’s pitch and volume during playback, instead of creating different files.
+
+**Decide whether you need to play sound that’s fixed to the wearer or tracked by the wearer.** People perceive _fixed_ sound as if it’s pointed at them, regardless of the direction they look or the virtual objects they move. In contrast, people tend to perceive _tracked_ sound as coming from a particular object, so moving the object closer or farther away changes what they hear. In general, you want to use tracked sound to enhance the realism of your experience, but there could be cases where fixed sound is a good choice. For example, Mindfulness uses fixed sound to envelop the wearer in an engaging, peaceful setting.
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/playing-audio#watchOS)
+
+In watchOS, the system manages audio playback. An app can play short audio clips while it’s active and running in the foreground, or it can play longer audio that continues even when people lower their wrist or switch to another app. For developer guidance, see [Playing Background Audio](https://developer.apple.com/documentation/WatchKit/playing-background-audio).
+
+**Use the recommended encoding values for media assets.** Specifically, use the 64 kbps HE-AAC (High-Efficiency Advanced Audio Coding) format to produce good-quality audio with lower data requirements.
+
+**Consider** **presenting a Now Playing view so people can control current or recently played audio without leaving your app.** The system-provided Now Playing view also displays information about the current audio source — which might be another app on a person’s Apple Watch or iPhone — and automatically selects the current or most recently used source. For developer guidance, see [Adding a Now Playing View](https://developer.apple.com/documentation/WatchKit/adding-a-now-playing-view).
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/playing-audio#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/playing-audio#Related)
+
+[Playing video](https://developer.apple.com/design/human-interface-guidelines/playing-video)
+
+[Feedback](https://developer.apple.com/design/human-interface-guidelines/feedback)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/playing-audio#Developer-documentation)
+
+[Configuring your app for media playback](https://developer.apple.com/documentation/AVFoundation/configuring-your-app-for-media-playback) — AVFoundation
+
+[`AVAudioSession`](https://developer.apple.com/documentation/AVFAudio/AVAudioSession) — AVFAudio
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/playing-audio#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/D35E0E85-CCB6-41A1-B227-7995ECD83ED5/FAD92809-C8B7-4968-802C-C662B1AF6C94/8340_wide_250x141_1x.jpg) Explore immersive sound design ](https://developer.apple.com/videos/play/wwdc2023/10271)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/D35E0E85-CCB6-41A1-B227-7995ECD83ED5/15489B11-8744-483D-AD38-EF78D8962FF4/8126_wide_250x141_1x.jpg) Principles of spatial design ](https://developer.apple.com/videos/play/wwdc2023/10072)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/119/28DB1BEB-3F4F-4418-ACD3-779DBFB889CB/5196_wide_250x141_1x.jpg) Immerse your app in Spatial Audio ](https://developer.apple.com/videos/play/wwdc2021/10265)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/playing-audio#Change-log)
+
+Date| Changes  
+---|---  
+June 21, 2023| Updated to include guidance for visionOS.  
+  

package/templates/skills/extended/other/hig-patterns/references/playing-haptics.md

@@ -0,0 +1,280 @@
+---
+title: "Playing haptics | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/playing-haptics
+
+# Playing haptics
+
+Playing haptics can engage people’s sense of touch and bring their familiarity with the physical world into your app or game.
+
+![A sketch of a horizontal line of three slightly overlapping circles, suggesting vibration. The image is overlaid with rectangular and circular grid lines and is tinted orange to subtly reflect the orange in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/367115f42d7b6235a3087fd140366955/patterns-playing-haptics-intro%402x.png)
+
+Depending on the platform and the device people are using, the system can play haptics in addition to visual and auditory feedback. For example, components like switches, sliders, and pickers automatically play haptic feedback on supported iPhone models; on Apple Watch, the Taptic Engine generates haptics for a number of built-in feedback patterns, which watchOS combines with an audible tone. On a Mac that’s equipped with a Force Touch trackpad, an app can play haptics while people drag content or when they force click to change the speed of media controls.
+
+In addition to built-in haptic capabilities, some external input devices can also play haptics. For example:
+
+  * In an iPadOS, macOS, tvOS, or visionOS app or game, [game controllers](https://developer.apple.com/design/human-interface-guidelines/game-controls) can provide haptic feedback (for developer guidance, see [Playing Haptics on Game Controllers](https://developer.apple.com/documentation/CoreHaptics/playing-haptics-on-game-controllers)).
+
+  * [Apple Pencil Pro](https://developer.apple.com/design/human-interface-guidelines/apple-pencil-and-scribble) and some trackpads can provide haptic feedback when connected to certain iPad models. (For details on Apple Pencil features and compatibility, see [Apple Pencil](https://www.apple.com/apple-pencil/).)
+
+
+
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Best-practices)
+
+**Use system-provided haptic patterns according to their documented meanings.** People recognize standard haptics because the system plays them consistently on interactions with standard controls. If the documented use case for a pattern doesn’t make sense in your app or game, avoid using the pattern to mean something else. Instead, use a generic pattern or create your own, where supported. For guidance, see [Custom haptics](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Custom-haptics).
+
+**Use haptics consistently throughout your app or game.** It’s important to build a clear, causal relationship between each haptic and the action that causes it so people learn to associate certain haptic patterns with certain experiences. If a haptic doesn’t reinforce a cause-and-effect relationship, it can be confusing and seem gratuitous. For example, if your game plays a specific haptic pattern when a character fails to finish a mission, people associate that pattern with a negative outcome. If you use the same haptic pattern for a positive outcome like a level completion, people will be confused.
+
+**Prefer using haptics to complement other feedback in your app or game.** When visual, auditory, and tactile feedback are in harmony — as they generally are in the physical world — the user experience is more coherent and can seem more natural. For example, you generally want to match the intensity and sharpness of a haptic with the intensity and sharpness of the animation it accompanies. You can also synchronize sound with haptics; for developer guidance, see [Delivering Rich App Experiences with Haptics](https://developer.apple.com/documentation/CoreHaptics/delivering-rich-app-experiences-with-haptics).
+
+**Avoid overusing haptics.** Sometimes a haptic can feel just right when it happens occasionally, but become tiresome when it plays frequently. Doing user testing can help you discover a balance that most people appreciate. Often, the best haptic experience is one that people may not be conscious of, but miss when it’s turned off.
+
+**In most apps, prefer playing short haptics that complement discrete events.** Although long-running haptics that accompany a gameplay flow can enhance the experience, long-running haptics in an app can dilute the meaning of the feedback and distract people from their task. On Apple Pencil Pro, for example, continuous or long-lasting haptics don’t tend to clarify the writing or drawing experience and can even make holding the pencil less pleasant.
+
+**Make haptics optional.** Let people turn off or mute haptics, and make sure people can still enjoy your app or game without them.
+
+**Be aware that playing haptics might impact other user experiences.** By design, haptics produce enough physical force for people to feel the vibration. Ensure that haptic vibrations don’t disrupt experiences involving device features like the camera, gyroscope, or microphone.
+
+## [Custom haptics](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Custom-haptics)
+
+Games often use custom haptics to enhance gameplay. Although it’s less common, nongame apps might also use custom haptics to provide a richer, more delightful experience.
+
+You can design custom haptic patterns that vary dynamically, based on user input or context. For example, the impact players feel when a game character jumps from a tree can be stronger than when the character jumps in place, and substantial experiences — like a collision or a hit — can feel very different from subtle experiences like the approach of footsteps or a looming danger.
+
+There are two basic building blocks you can use to generate custom haptic patterns.
+
+  * _Transient_ events are brief and compact, often feeling like taps or impulses. The experience of tapping the Flashlight button on the Home Screen is an example of a transient event.
+
+  * _Continuous_ events feel like sustained vibrations, such as the experience of the lasers effect in a message.
+
+
+
+
+Regardless of the type of haptic event you use to generate a custom haptic, you can also control its _sharpness_ and _intensity_. You can think of sharpness as a way to abstract a haptic experience into the waveform that produces the corresponding physical sensations. Specifying sharpness lets you relay to the system your intent for the experience. For example, you might use sharpness values to convey an experience that’s soft, rounded, or organic, or one that’s crisp, precise, or mechanical. As the term implies, intensity means the strength of the haptic.
+
+By combining transient and continuous events, varying sharpness and intensity, and including optional audio content, you can create a wide range of different haptic experiences. For developer guidance, see [Core Haptics](https://developer.apple.com/documentation/CoreHaptics).
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Platform-considerations)
+
+### [iOS](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#iOS)
+
+On supported iPhone models, you can add haptics to your experience in the following ways:
+
+  * Use standard UI components — like [toggles](https://developer.apple.com/design/human-interface-guidelines/toggles), [sliders](https://developer.apple.com/design/human-interface-guidelines/sliders), and [pickers](https://developer.apple.com/design/human-interface-guidelines/pickers) — that play Apple-designed system haptics by default.
+
+  * When it makes sense, use a feedback generator to play one of several predefined haptic patterns in the categories of [notification](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Notification), [impact](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Impact), and [selection](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Selection) (for developer guidance, see [`UIFeedbackGenerator`](https://developer.apple.com/documentation/UIKit/UIFeedbackGenerator)).
+
+
+
+
+#### [Notification](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Notification)
+
+Notification haptics provide feedback about the outcome of a task or action, such as depositing a check or unlocking a vehicle.
+
+Video with custom controls. 
+
+Content description: An animation that represents a series of two haptic pulses of various durations and strengths by showing bars of different sizes and playing audio tones of different pitches. This particular pattern represents a success. 
+
+Play 
+
+**Success.** Indicates that a task or action has completed.
+
+Video with custom controls. 
+
+Content description: An animation that represents a series of two haptic pulses of various durations and strengths by showing bars of different sizes and playing audio tones of different pitches. This particular pattern represents a warning. 
+
+Play 
+
+**Warning.** Indicates that a task or action has produced a warning of some kind.
+
+Video with custom controls. 
+
+Content description: An animation that represents a series of four haptic pulses of various durations and strengths by showing bars of different sizes and playing audio tones of different pitches. This particular pattern represents an error. 
+
+Play 
+
+**Error.** Indicates that an error has occurred.
+
+#### [Impact](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Impact)
+
+Impact haptics provide a physical metaphor you can use to complement a visual experience. For example, people might feel a tap when a view snaps into place or a thud when two heavy objects collide.
+
+Video with custom controls. 
+
+Content description: An animation that represents a single haptic pulse of a specific duration and strength by showing a bar of a specific size and playing an audio tone of a specific pitch. This particular pattern represents a light impact. 
+
+Play 
+
+**Light.** Indicates a collision between small or lightweight UI objects.
+
+Video with custom controls. 
+
+Content description: An animation that represents a single haptic pulse of a specific duration and strength by showing a bar of a specific size and playing an audio tone of a specific pitch. This particular pattern represents a medium impact. 
+
+Play 
+
+**Medium.** Indicates a collision between medium-sized or medium-weight UI objects.
+
+Video with custom controls. 
+
+Content description: An animation that represents a single haptic pulse of a specific duration and strength by showing a bar of a specific size and playing an audio tone of a specific pitch. This particular pattern represents a heavy impact. 
+
+Play 
+
+**Heavy.** Indicates a collision between large or heavyweight UI objects.
+
+Video with custom controls. 
+
+Content description: An animation that represents a single haptic pulse of a specific duration and strength by showing a bar of a specific size and playing an audio tone of a specific pitch. This particular pattern represents a rigid impact. 
+
+Play 
+
+**Rigid.** Indicates a collision between hard or inflexible UI objects.
+
+Video with custom controls. 
+
+Content description: An animation that represents a single haptic pulse of a specific duration and strength by showing a bar of a specific size and playing an audio tone of a specific pitch. This particular pattern represents a soft impact. 
+
+Play 
+
+**Soft.** Indicates a collision between soft or flexible UI objects.
+
+#### [Selection](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Selection)
+
+Selection haptics provide feedback while the values of a UI element are changing.
+
+Video with custom controls. 
+
+Content description: An animation that represents a single haptic pulse of a specific duration and strength by showing a bar of a specific size and playing an audio tone of a specific pitch. This particular pattern represents a selection. 
+
+Play 
+
+**Selection.** Indicates that a UI element’s values are changing.
+
+### [macOS](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#macOS)
+
+When a Magic Trackpad is available, your app can provide one of the three following haptic patterns in response to a drag operation or force click.
+
+Haptic feedback pattern| Description  
+---|---  
+Alignment| Indicates the alignment of a dragged item. For example, this pattern could be used in a drawing app when the people drag a shape into alignment with another shape. Other scenarios where this type of feedback could be used might include scaling an object to fit within specific dimensions, positioning an object at a preferred location, or reaching the beginning/end or minimum/maximum of something like a scrubber in a video app.  
+Level change| Indicates movement between discrete levels of pressure. For example, as people press a fast-forward button on a video player, playback could increase or decrease and haptic feedback could be provided as different levels of pressure are reached.  
+Generic| Intended for providing general feedback when the other patterns don’t apply.  
+  
+For developer guidance, see [`NSHapticFeedbackPerformer`](https://developer.apple.com/documentation/AppKit/NSHapticFeedbackPerformer).
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#watchOS)
+
+Apple Watch Series 4 and later provides haptic feedback for the Digital Crown, which gives people a more tactile experience as they scroll through content. By default, the system provides linear haptic detents that people can feel as they rotate the Digital Crown. Some system controls, like table views, provide detents as new items scroll onto the screen. For developer guidance, see [`WKHapticType`](https://developer.apple.com/documentation/WatchKit/WKHapticType).
+
+watchOS defines the following set of haptics, each of which conveys a specific meaning to people.
+
+  * Notification 
+  * Up 
+  * Down 
+  * Success 
+  * Failure 
+  * Retry 
+  * Start 
+  * Stop 
+  * Click 
+
+
+
+Video with custom controls. 
+
+Content description: An animation that represents an arrangement of haptic pulses of various durations and strengths by showing a set of thin vertical lines that symbolize sound waves. 
+
+Play 
+
+**Notification.** Tells the person that something significant or out of the ordinary has happened and requires their attention. The system plays this same haptic when a local or remote notification arrives.
+
+Video with custom controls. 
+
+Content description: An animation that represents an arrangement of haptic pulses of various durations and strengths by showing a set of thin vertical lines that symbolize sound waves. 
+
+Play 
+
+**Up.** Tells the person that an important value increased above a significant threshold.
+
+Video with custom controls. 
+
+Content description: An animation that represents an arrangement of haptic pulses of various durations and strengths by showing a set of thin vertical lines that symbolize sound waves. 
+
+Play 
+
+**Down.** Tells the person that an important value decreased below a significant threshold.
+
+Video with custom controls. 
+
+Content description: An animation that represents an arrangement of haptic pulses of various durations and strengths by showing a set of thin vertical lines that symbolize sound waves. 
+
+Play 
+
+**Success.** Tells the person that an action completed successfully.
+
+Video with custom controls. 
+
+Content description: An animation that represents an arrangement of haptic pulses of various durations and strengths by showing a set of thin vertical lines that symbolize sound waves. 
+
+Play 
+
+**Failure.** Tells the person that an action failed.
+
+Video with custom controls. 
+
+Content description: An animation that represents an arrangement of haptic pulses of various durations and strengths by showing a set of thin vertical lines that symbolize sound waves. 
+
+Play 
+
+**Retry.** Tells the person that an action failed but they can retry it.
+
+Video with custom controls. 
+
+Content description: An animation that represents an arrangement of haptic pulses of various durations and strengths by showing a set of thin vertical lines that symbolize sound waves. 
+
+Play 
+
+**Start.** Tells the person that an activity started. Use this haptic when starting a timer or any other activity that a person can explicitly start and stop. The stop haptic usually follows this haptic.
+
+Video with custom controls. 
+
+Content description: An animation that represents an arrangement of haptic pulses of various durations and strengths by showing a set of thin vertical lines that symbolize sound waves. 
+
+Play 
+
+**Stop.** Tells the person that an activity stopped. Use this haptic when stopping a timer or other activity that the person previously started.
+
+Video with custom controls. 
+
+Content description: An animation that represents an arrangement of haptic pulses of various durations and strengths by showing a set of thin vertical lines that symbolize sound waves. 
+
+Play 
+
+**Click.** Provides the sensation of a dial clicking, helping you communicate progress at predefined increments or intervals. Overusing the click haptic tends to diminish its utility and can even be confusing when clicks overlap each other.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Related)
+
+[Feedback](https://developer.apple.com/design/human-interface-guidelines/feedback)
+
+[Gestures](https://developer.apple.com/design/human-interface-guidelines/gestures)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Developer-documentation)
+
+[Core Haptics](https://developer.apple.com/documentation/CoreHaptics)
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/119/100FA6DD-1A48-485A-AFC2-47FDB92376D3/5210_wide_250x141_1x.jpg) Practice audio haptic design ](https://developer.apple.com/videos/play/wwdc2021/10278)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/48/9EEAE751-B5EE-4934-8F3A-38361FBA05DE/3277_wide_250x141_1x.jpg) Introducing Core Haptics ](https://developer.apple.com/videos/play/wwdc2019/520)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Change-log)
+
+Date| Changes  
+---|---  
+May 7, 2024| Added guidance for playing haptics on Apple Pencil Pro.  
+June 21, 2023| Updated to include guidance for visionOS.  
+  

package/templates/skills/extended/other/hig-patterns/references/playing-video.md

@@ -0,0 +1,180 @@
+---
+title: "Playing video | Apple Developer Documentation"
+source: https://developer.apple.com/design/human-interface-guidelines/playing-video
+
+# Playing video
+
+People expect to enjoy rich video experiences on their devices, regardless of the app or game they’re using.
+
+![A sketch of a play button, suggesting video playback. The image is overlaid with rectangular and circular grid lines and is tinted orange to subtly reflect the orange in the original six-color Apple logo.](https://docs-assets.developer.apple.com/published/26e9c68a8a956a2f5ed6b1d9988c0dce/patterns-playing-video-intro%402x.png)
+
+The system provides video players designed for you to use to embed playback experiences within your app or game in iOS, iPadOS, macOS, tvOS, and visionOS. You can also offer your content through the TV app in these platforms, which gives people a convenient and consistent viewing experience.
+
+The system-provided video players support different aspect-ratio playback modes and in most platforms, Picture in Picture (PiP) viewing mode. Although people can switch modes during playback, by default, the system selects one of the following playback modes based on a video’s aspect ratio:
+
+  * In full-screen — or _aspect-fill_ — mode, the video scales to fill the display, and some edge cropping may occur. This mode is the default for wide video (2:1 through 2.40:1). For developer guidance, see [`resizeAspectFill`](https://developer.apple.com/documentation/AVFoundation/AVLayerVideoGravity/resizeAspectFill).
+
+  * In fit-to-screen — or _aspect_ — mode, the entire video is visible onscreen, and letterboxing or pillarboxing occurs as needed. This mode is the default for standard video (4:3, 16:9, and anything up to 2:1) and ultrawide video (anything above 2.40:1). For developer guidance, see [`resizeAspect`](https://developer.apple.com/documentation/AVFoundation/AVLayerVideoGravity/resizeAspect).
+
+
+
+
+In visionOS and tvOS, the built-in video player also provides _transport controls,_ which let people perform playback tasks, like turning on subtitles or changing the audio language, and actions, like adding a show to a library or favoriting a clip. Below the transport controls, the video player displays _content tabs_ , like Info, Episodes, or Chapters, that can provide supporting information and help streamline navigation. In visionOS, the transport controls appear as an [ornament](https://developer.apple.com/design/human-interface-guidelines/ornaments).
+
+## [Best practices](https://developer.apple.com/design/human-interface-guidelines/playing-video#Best-practices)
+
+**Use the system video player to give people a familiar and convenient experience.** The built-in video player provides an exceptional video playback experience that offers consistent interactions and behaviors that let people concentrate on enjoying immersive content. If your app truly requires a custom video player, reference the behavior and interface of the system video player to help you provide an experience that people can instantly understand. A custom experience that diverges slightly from the system-provided experience can cause frustration because people don’t know which of their habitual interactions they can continue to use.
+
+**Always display video content at its original aspect ratio.** When video content uses embedded letterbox or pillarbox padding to conform to a specific aspect ratio, the system may be unable to correctly scale the video based on the current playback mode. Padding embedded within the video frame can cause videos to appear smaller in both full-screen and fit-to-screen modes. It also prevents videos from displaying correctly in edge-to-edge, non-full-screen contexts, like Picture in Picture mode on iPad.
+
+Here are some examples that show how padding can affect video display on iPhone Xs.
+
+  * Result of padding a 4:3 video 
+  * Result of padding a 21:9 video 
+
+
+
+![An illustration of iPhone in landscape orientation. A blue rectangle shows the AVKit safe area within the screen. Overlaying the safe area and extending beyond it on all sides is a purple rectangle that represents the 4:3 video area, which doesn't include any embedded padding.](https://docs-assets.developer.apple.com/published/d0ed256c73ed2b5b8cba4baf20d437e1/video-fill-4-3-right%402x.png)
+
+![A checkmark in a circle to indicate correct usage.](https://docs-assets.developer.apple.com/published/88662da92338267bb64cd2275c84e484/checkmark%402x.png)4:3 video in full-screen viewing mode
+
+![An illustration of iPhone in landscape orientation. A blue rectangle shows the AVKit safe area within the screen. Overlaying the safe area and extending beyond its top and bottom edges is a purple rectangle that represents the 4:3 video area. Attached to the left and right edges of the purple rectangle are two vertical pink rectangles that extend to the left and right device edges, representing embedded pillarboxes.](https://docs-assets.developer.apple.com/published/f6c10e1815aabff99ace1a053ba75757/video-fill-4-3-wrong%402x.png)
+
+![An X in a circle to indicate incorrect usage.](https://docs-assets.developer.apple.com/published/209f6f0fc8ad99d9bf59e12d82d06584/crossout%402x.png)4:3 video with embedded padding, in full-screen viewing mode
+
+![A legend for the illustrations, identifying blue as the AVKit safe area, purple as the video area, and pink as the embedded padding.](https://docs-assets.developer.apple.com/published/fc703118ebdf69f3c70d70ffce64727e/legend-letter-pillar%402x.png)
+
+![An illustration of iPhone in landscape orientation. A blue rectangle shows the AVKit safe area within the screen. Overlaying the safe area and extending to the top and bottom edges of the device is a purple rectangle representing the 21:9 video area, which doesn't include any embedded padding.](https://docs-assets.developer.apple.com/published/bc4f68b42fb171bb35e19393dbe741f1/video-fit-21-9-right%402x.png)
+
+![A checkmark in a circle to indicate correct usage.](https://docs-assets.developer.apple.com/published/88662da92338267bb64cd2275c84e484/checkmark%402x.png)21:9 video in fit-to-screen viewing mode
+
+![An illustration of iPhone in landscape orientation. A blue rectangle shows the AVKit safe area within the screen. Overlaying the safe area is a purple rectangle representing the 21:9 video area plus two horizontal pink rectangles attached to its top and bottom edges, representing embedded letterboxes. The area that includes the video and the letterboxes extends to the top and bottom edges of the device, but doesn't extend to the left and right edges of the safe area.](https://docs-assets.developer.apple.com/published/ce74b05ac601afa8404fd40db9cc8380/video-fit-21-9-wrong%402x.png)
+
+![An X in a circle to indicate incorrect usage.](https://docs-assets.developer.apple.com/published/209f6f0fc8ad99d9bf59e12d82d06584/crossout%402x.png)21:9 video with embedded padding, in fit-to-screen viewing mode
+
+![A legend for the illustrations, identifying blue as the AVKit safe area, purple as the video area, and pink as the embedded padding.](https://docs-assets.developer.apple.com/published/fc703118ebdf69f3c70d70ffce64727e/legend-letter-pillar%402x.png)
+
+**Provide additional information when it adds value.** In iOS, iPadOS, tvOS, and visionOS, you can customize a video’s additional information by providing an image, title, description, and other useful information. In general, restrict this content so that it doesn’t obscure media playback. For developer guidance, see [`externalMetadata`](https://developer.apple.com/documentation/AVFoundation/AVPlayerItem/externalMetadata).
+
+**Support the interactions people expect, regardless of the input device they’re using to control playback.** For example, people expect to press Space on a connected keyboard to play or pause media playback on Apple Vision Pro, Mac, iPhone, iPad, and Apple TV. Similarly, people expect to move through their media on Apple TV by making familiar, intuitive gestures with the Siri Remote. For guidance, see Keyboards and Remotes.
+
+**If people need to access playback options or content-specific information in your tvOS app, consider adding a transport control or a custom content tab.** People typically open a transport control or content tab while they’re watching a video, so it’s essential to provide only the most useful actions and information. Help people return quickly to the viewing experience by making sure your actions don’t take more than a step or two and your content is succinct. Use a transport control to support a playback-related action like favoriting a video; use custom content tabs to display supplementary information or recommendations.
+
+**Avoid allowing audio from different sources to mix as viewers switch between modes.** Mixed audio is an unpleasant and frustrating user experience. In general, audio mixes when at least one of the audio sources fails to handle secondary audio correctly. Here is a typical scenario: While watching a full-screen video, the viewer moves it into the PiP window, where the system automatically mutes the video. In the full-screen window, the viewer starts a game that plays background music, then switches to the PiP window and unmutes the video. If the game doesn’t handle secondary audio appropriately, its audio mixes with the audio from the unmuted video. For developer guidance, see [`silenceSecondaryAudioHintNotification`](https://developer.apple.com/documentation/AVFAudio/AVAudioSession/silenceSecondaryAudioHintNotification).
+
+## [Integrating with the TV app](https://developer.apple.com/design/human-interface-guidelines/playing-video#Integrating-with-the-TV-app)
+
+The TV app provides global access to favorite, recently played, and recommended video content from across the system. When people initiate content playback within your app, the TV app automatically opens your app and transitions to it. Follow these guidelines to help the TV app experience feel like an integrated part of your app.
+
+**Ensure a smooth transition to your app.** The TV app fades to black when transitioning to your app and doesn’t show your app’s launch screen. Maintain visual continuity with this transition by immediately presenting your own black screen before starting to play or resume content.
+
+**Show the expected content immediately.** People expect the content they choose to begin playing as soon as the transition to your app completes, especially when resuming playback. Jump right from your app’s black screen into content, and avoid displaying splash screens, detail screens, intro animations, or any other barriers that make it take longer to reach content. In rare situations where you must display an interstitial element before the selected media plays, people can choose Select to step through the element, or choose Play if they want to skip the interstitial content and start playback.
+
+**Avoid asking people if they want to resume playback.** If playback can be resumed, do so automatically without prompting for confirmation.
+
+**Play or pause playback when people press Space on a connected Bluetooth keyboard.** Pressing Space to control media playback is an interaction people expect, regardless of the keyboard they’re using.
+
+**Make sure content plays for the correct viewer.** If your app supports multiple user profiles, the TV app can specify a profile when issuing a playback request. Make your app automatically switch to this profile before starting playback. If a playback request doesn’t specify a profile, ask the viewer to choose one before playback begins so this information is available in the future.
+
+**Use the previous end time when resuming playback of a long video clip.** Resuming playback at the previous stopping point lets people quickly continue where they left off.
+
+### [Loading content](https://developer.apple.com/design/human-interface-guidelines/playing-video#Loading-content)
+
+**Avoid displaying loading screens when possible.** A loading screen is unnecessary if your content loads quickly, but if loading takes more than two seconds, consider showing a black loading screen with a centered activity spinner and no surrounding content.
+
+**Start playback immediately.** If you must display a loading screen, display it only until enough content loads for playback to begin. Continue loading remaining content in the background.
+
+**Minimize loading screen content.** If you include branding or images on your loading screen, do so minimally while maintaining the black background that helps provide a seamless transition to playback.
+
+### [Exiting playback](https://developer.apple.com/design/human-interface-guidelines/playing-video#Exiting-playback)
+
+After exiting playback, people remain in your app rather than returning to the TV app, so it’s a good idea to help them avoid becoming disoriented.
+
+**Show a contextually relevant screen.** When exiting playback, display a detail view for the content the viewer was just watching and include an option to resume playback. If a detail view isn’t available, show either a menu that lists this content or your app’s main menu.
+
+**Be prepared for an immediate exit.** Prepare an exit view as soon as possible after receiving a playback notification so you’re ready to display the view if people exit immediately after playback begins.
+
+## [Platform considerations](https://developer.apple.com/design/human-interface-guidelines/playing-video#Platform-considerations)
+
+ _No additional considerations for iOS, iPadOS, or macOS._
+
+### [tvOS](https://developer.apple.com/design/human-interface-guidelines/playing-video#tvOS)
+
+**Defer to content when displaying logos or noninteractive overlays above video.** A small, unobtrusive logo or countdown timer may be appropriate for your video, but avoid large, distracting overlays that don’t enhance the viewing experience. Also, be aware that some devices are prone to image retention, so it’s generally better to keep overlays short and to prefer translucent graphics in Standard Dynamic Range (SDR) to bright, opaque content.
+
+**Show interactive overlays gracefully.** Some videos display interactive overlays, such as quizzes, surveys, and progress check-ins. For the best user experience, implement a minimum delay of 0.5 seconds to pause playing media, and display an interactive overlay. Give people a clear way to dismiss the overlay and resume media playback after they finish interacting.
+
+### [visionOS](https://developer.apple.com/design/human-interface-guidelines/playing-video#visionOS)
+
+**Help people stay comfortable when playing video in your app.** Often, an app doesn’t control the content in the videos it plays, but you can help people stay comfortable by:
+
+  * Letting them choose when to start playing a video
+
+  * Using a small window for playback, letting people resize it if they want
+
+  * Making sure people can see their surroundings during playback
+
+
+
+
+**In a fully immersive experience, avoid letting virtual content obscure playback or transport controls.** In a fully immersive context, the system automatically places the video player at a predictable location that provides an optimal viewing experience. Use this location to help make sure that no virtual content occludes the default playback or transport controls in the ornament near the bottom of the player.
+
+**Avoid automatically starting a fully immersive video playback experience.** People need control over their experience and they’re unlikely to appreciate being launched into a fully immersive video without warning.
+
+**Create a thumbnail track if you want to support scrubbing.** The system displays thumbnails as people scrub to different times in the video, helping them choose the section they want. To improve performance, supply a set of thumbnails that each measure 160 px in width. For developer guidance, see [HTTP Live Streaming (HLS) Authoring Specification for Apple Devices > Trick Play](https://developer.apple.com/documentation/http-live-streaming/hls-authoring-specification-for-apple-devices#Trick-Play).
+
+**Avoid expanding an inline video player to fill a window.** When you display the system-provided player view in a window, playback controls appear in the same plane as the player view and not in an ornament that floats above the window. Inline video needs to be 2D and you want to make sure that window content remains visible around the player so people don’t expect a more immersive playback experience. For developer guidance, see [`AVPlayerViewController`](https://developer.apple.com/documentation/AVKit/AVPlayerViewController).
+
+**Use a RealityKit video player if you need to play video in a view like a splash screen or a transitional view.** In situations like these, people generally expect the video to lead into the next experience, so they don’t need playback controls or system-provided integration, like dimming and view anchoring. The RealityKit video player automatically uses the correct aspect ratio for both 2D and 3D video and supports closed captions. RealityKit can also help you play video as a special effect on the surface of a custom view or object. For developer guidance, see [RealityKit](https://developer.apple.com/documentation/RealityKit).
+
+### [watchOS](https://developer.apple.com/design/human-interface-guidelines/playing-video#watchOS)
+
+In watchOS, the system manages video playback. Apps can play short video clips while the app is active and running in the foreground. You can use a movie element to embed clips in your interface and play video inline, or you can play a clip in a separate interface. For developer guidance, see [`VideoPlayer`](https://developer.apple.com/documentation/AVKit/VideoPlayer).
+
+**Keep video clips short.** Prefer shorter clips of no longer than 30 seconds. Long clips consume more disk space and require people to keep their wrists raised for longer periods of time, which can cause fatigue.
+
+**Use the recommended sizes and encoding values for media assets.** In particular, avoid scaling video clips, which affects performance and results in a suboptimal appearance. The following table lists the recommended encoding and resolution values for video assets. The audio encoding values apply to both movies and audio-only assets.
+
+Attribute| Value  
+---|---  
+Video codec| H.264 High Profile  
+Video bit rate| 160 kbps at up to 30 fps  
+Resolution (full screen)| 208x260 px (portrait orientation)  
+Resolution (16:9)| 320x180 px (landscape orientation)  
+Audio| 64 kbps HE-AAC  
+  
+**Avoid creating a poster image that looks like a system control.** You want people to understand that they can tap a movie element for playback; you don’t want to confuse people by making movie elements look like something else.
+
+**Consider creating a poster image that represents a video clip’s contents.** When people tap a poster image, the system replaces the image with the video and begins inline playback. A relevant poster image can help people make an informed decision about whether to view the video. In general, avoid creating a poster image that has nothing to do with the content or that people might mistake for a control.
+
+## [Resources](https://developer.apple.com/design/human-interface-guidelines/playing-video#Resources)
+
+#### [Related](https://developer.apple.com/design/human-interface-guidelines/playing-video#Related)
+
+[Playing audio](https://developer.apple.com/design/human-interface-guidelines/playing-audio)
+
+[Feedback](https://developer.apple.com/design/human-interface-guidelines/feedback)
+
+#### [Developer documentation](https://developer.apple.com/design/human-interface-guidelines/playing-video#Developer-documentation)
+
+[Configuring your app for media playback](https://developer.apple.com/documentation/AVFoundation/configuring-your-app-for-media-playback) — AVFoundation
+
+[AVKit](https://developer.apple.com/documentation/AVKit)
+
+[HTTP Live Streaming](https://developer.apple.com/streaming/)
+
+#### [Videos](https://developer.apple.com/design/human-interface-guidelines/playing-video#Videos)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/124/344FB830-5184-4C63-8D0C-D8861D31A70D/6645_wide_250x141_1x.jpg) Create a great video playback experience ](https://developer.apple.com/videos/play/wwdc2022/10147)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/3055294D-836B-4513-B7B0-0BC5666246B0/3F1BA6AB-BC74-4A1A-A440-90BA4AE5A23D/10042_wide_250x141_1x.jpg) Explore video experiences for visionOS ](https://developer.apple.com/videos/play/wwdc2025/304)
+
+[![](https://devimages-cdn.apple.com/wwdc-services/images/119/53F0161E-DB14-4A7D-8A94-B76244201AB8/5102_wide_250x141_1x.jpg) Deliver a great playback experience on tvOS ](https://developer.apple.com/videos/play/wwdc2021/10191)
+
+## [Change log](https://developer.apple.com/design/human-interface-guidelines/playing-video#Change-log)
+
+Date| Changes  
+---|---  
+September 12, 2023| Corrected the recommended width for a thumbnail in visionOS.  
+June 21, 2023| Updated to include guidance for visionOS.  
+