安装 • 使用 • 文档 • 为什么我建造了一个钢琴 • 许可证 • 贡献 • 有问题吗？ • 致谢
Piano 是一个围绕 AVFoundation 和 UIHapticFeedback 框架构建的 便捷 且 易于使用 的封装器，充分利用了 触觉引擎 的全部功能。同时，它遵循 Apple 的严格指南来 保护电池寿命。最终，Piano 允许您，即作曲家，指挥出优美的交响乐，并在您的应用程序或游戏中获得更沉浸、更实用、更有意义的用户体验。
兼容性
Piano 需要 iOS 10+，并且与 Swift 4.2 项目兼容。
安装
- CocoaPods 的安装指南
platform :ios, '10.0'
target 'ProjectName' do
use_frameworks!
pod 'Piano', '~> 1.8'
end(如果遇到问题，请运行 pod repo update 并重试)
- Carthage 的安装指南
github "saoudrizwan/Piano"(在使用 CocoaPods 或 Carthage 和 Swift 4 框架之前，请确保 Xcode 10 是您系统的默认 Xcode)
- 或者将 Piano 框架嵌入到您的项目中
然后在您希望使用其的文件中导入 import Piano。
使用
使用 Piano 很简单。
let symphony: [Piano.Note] = [
.sound(.asset(name: "acapella")),
.hapticFeedback(.impact(.light)),
.waitUntilFinished,
.hapticFeedback(.impact(.heavy)),
.wait(0.2),
.sound(.system(.chooChoo))
]
Piano.play(symphony)... 或者更简单的方法
🎹.play([
.sound(.asset(name: "acapella"))
])可选地添加一个完成块，在所有音符播放完毕时调用
🎹.play([
.sound(.asset(name: "acapella"))
]) {
// ...
}或取消正在播放的交响乐
🎹.cancel()在后台，每个音符都有一个内部完成块，因此您可以添加一个.waitUntilFinished音符，告诉Piano在上一音符播放完毕之前不要播放下一个音符。这对于创建自定义触觉反馈模式非常有用，除了Apple预定义的那些。这对于创建复杂的声音效果和振动组合也非常出色。
音符
.sound(Audio)
播放音频文件。
| 音频 | |
|---|---|
.asset(name: String) |
任何.xcassets目录中资产的名称。建议将您的声音文件添加到资源库中，而不是将其作为独立的文件添加到主包中。 |
.file(name: String, extension: String) |
从主包检索文件。例如，名为Beep.wav的文件将通过.file(name: "Beep", extension: "wav")访问。 |
.url(URL) |
这仅适用于文件URL，不适用于网络URL。 |
.system(SystemSound) |
每个iPhone都预定义的系统声音。在此处查看所有可用选项。 |
.vibration(Vibration)
播放所有iPhone型号上可用的标准振动。
| 振动 | |
|---|---|
.default |
基本的1秒振动 |
.alert |
两个连续的短振动 |
.tapticEngine(TapticEngine)
播放仅在iPhone 6S及以上可用的Taptic Engine振动。
| TapticEngine | |
|---|---|
.peek |
一次轻弱的震动 |
.pop |
一次强烈的震动 |
.cancelled |
三次连续的弱震动 |
.tryAgain |
一次弱震动然后一次强震动 |
.failed |
三次连续的强震动 |
.hapticFeedback(HapticFeedback)
在iPhone 7及以上版本的手机上播放Taptic Engine触觉反馈。
| HapticFeedback | ||
|---|---|---|
.notification(Notification) |
Notification | 表示任务或操作已成功、失败或产生某种类型的警告。 |
.success |
表示任务或操作已成功完成。 | |
.warning |
表示任务或操作已产生警告。 | |
.failure |
表示任务或操作已失败。 | |
.impact(Impact) |
Impact | 表示发生了碰撞。例如，当用户界面对象碰撞或固定的时分发碰撞反馈。 |
.light |
表示小型轻量级用户界面元素碰撞的物理隐喻。 | |
.medium |
表示中量级用户界面元素碰撞的物理隐喻。 | |
.heavy |
表示大型重型用户界面元素碰撞的物理隐喻。 | |
.selection |
表示选择正在积极变化。例如，当在选择器轮上滚动时，用户体验到轻拍。 |
.waitUntilFinished
告诉钢琴等待前一音符播放完毕后，再播放下一个音符。
.wait(TimeInterval)
告诉钢琴等待指定的时间后，再播放下一个音符。
设备功能
-
iPhone 6S和6S Plus携带第一代Taptic Engine，有几种“触觉”振动模式，您可以使用Piano的
.tapticEngine()音符进行操作。 -
iPhone 7及以上版本携带最新版本的Taptic Engine，支持iOS 10触觉反馈框架，允许您选择更多振动类型。您可以使用
.hapticFeedback()音符播放这些振动。 -
所有版本的iPhone都能播放
.vibration()音符。
钢琴还包含了一个用于检查用户设备是否具有Taptic Engine以及是否支持触觉反馈的UIDevice扩展。此扩展特别适用于为所有设备创建交响曲。
if UIDevice.current.hasHapticFeedback {
// use .hapticFeedback(HapticFeedback) notes
} else if UIDevice.current.hasTapticEngine {
// use .tapticEngine(TapticEngine) notes
} else {
// use .vibration(Vibration) notes
}注意：此扩展在模拟器上不工作，它始终返回false。
触觉引擎指南
Apple关于触觉反馈框架的指南非常明确，合适地使用触觉引擎以避免耗尽用户的电池电量。钢琴正是考虑到这一点而构建的，并以尽可能高的效率处理大多数情况。但您可以通过根据具体需求调用这些辅助方法来帮助保存电池寿命并进一步减少延迟。
1. 唤醒触觉引擎
Piano.wakeTapticEngine()这初始化并分配触觉反馈框架，并基本上“唤醒”触觉引擎，因为它通常处于空闲状态。一个好的放置位置是在手势或动作的开始状态，提前播放.hapticFeedback()音符。
2. 准备触觉引擎
Piano.prepareTapticEngine()这告诉触觉引擎在创建任何反馈之前进行准备，以减少触发反馈时的延迟。
来自Apple的文档
当尝试将反馈与声音或视觉提示匹配时，这一点尤为重要。为了保持电力，触觉引擎仅在很短的一段时间内保持这种准备状态（大约几秒钟），或者直到您下一次触发反馈。考虑一下您何时何地最能最好地准备您的生成器。如果在调用准备后立即触发反馈，系统可能没有足够的时间将触觉引擎置于准备状态，您可能看不到延迟的减少。另一方面，如果您过早地调用准备，触觉引擎可能在触发反馈前再次变得空闲。
总结：在调用.wakeTapticEngine()后，通常在手势或动作的开始，在准备播放.hapticFeedback()音符时放置此代码是一个好位置。
3. 将触觉引擎放回休眠状态
Piano.putTapticEngineToSleep()一旦我们知道不再使用触觉引擎，我们可以释放振动反馈框架，并将触觉引擎返回到空闲状态。一个好的地方是在完成、取消或失败的手势或动作结束时进行此操作。
但你不必这样做。
Piano在调用包含.hapticFeedback()音符的.play([ ... ])时，会自动唤醒并准备触觉引擎，并在音符演奏完成后将其放回休眠状态。
示例应用程序
此示例应用程序是您开始的好地方。它被设计成一个游乐场，您可以在这里创作和测试自己的声音和振动交响曲。
您甚至可以将自己的声音文件拖放到项目中，并稍微调整一些代码，看看您的声音如何在触觉引擎的帮助下工作。要添加您的声音文件，只需将其拖放到Sounds.xcassets中，根据需要命名，然后编辑ViewController.swift中的cellData属性（在cellData中查看case 7，或使用Ctrl + 6在跳转栏中查找“在此处添加您的声音资产...”）。
文档
按住选项键并点击Piano的任何方法或音符，即可获取详细的文档。请参阅以下图片：
为什么我建造钢琴
随着新iPhone 8和iPhone X的推出，我们将看到许多新的增强现实应用程序，而在《增强现实人机界面指南》中的一个关键点是不使增强现实视图杂乱，尽可能多地显示增强现实的内容。除了增强现实，苹果还投入了大量时间和人力，通过触觉引擎和Siri为iPhone提供了一个超越我们视野的界面。苹果甚至在WWDC 2017期间有一个环节讨论了声音设计的重要性及其对用户体验的影响。很明显，技术的未来不是视觉界面，而是增强我们与真实世界的联系。通过使用我们的物理、听觉和最重要的视觉感觉，我们可以以全新的视角看待世界。这就是我构建Piano和ARLogger的原因，我希望这些框架可以帮助开发人员创建沉浸式和无杂乱界面的同时，让用户了解技术的状态和目的。如果您需要我在AR项目上的帮助，或者只是想聊聊技术的未来，请不要犹豫，通过Twitter @sdrzn联系我。
许可证
Piano使用MIT许可证。如果您有任何问题或希望分享您如何使用Piano，请提交一个 issues。
贡献
请自由创建有关功能请求的 issues 或发送任何您认为将补充Piano及其哲学的添加请求的 pull requests。
有疑问吗？
请通过电子邮件 [email protected] 或通过Twitter @sdrzn联系我。如果您遇到错误或希望添加一个功能，请创建一个 issues。
致谢
- 来自 Icons 8 UI Sounds 的示例应用程序声音文件。
- README头部图片中的音符源自Noun Project上的LSE Design