Merge branch 'develop'

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1 @@
+Ready to send us a pull request? Please make sure your request is based on the [develop](https://github.com/audiokit/AudioKit/tree/develop) branch of the repository as `master` only holds stable releases.

.swiftlint.yml

@@ -58,7 +58,6 @@ opt_in_rules:
   - weak_delegate
   - force_cast
   - object_literal
-  - sorted_imports
   - line_length
   - attributes
   - force_unwrapping

AudioKit.podspec.json

@@ -1,6 +1,6 @@
 {
     "name": "AudioKit",
-    "version": "3.7",
+    "version": "3.7.1",
     "authors": {
         "Aurelius Prochazka": "audiokit@audiokit.io"
     },
@@ -12,7 +12,7 @@
     "social_media_url": "http://twitter.com/AudioKitMan",
     "documentation_url": "http://audiokit.io/docs/",
     "source": {
-        "http": "https://github.com/audiokit/AudioKit/releases/download/v3.7/AudioKit.framework.zip"
+        "http": "https://github.com/audiokit/AudioKit/releases/download/v3.7.1/AudioKit.framework.zip"
     },
     "summary": "Open-source audio synthesis, processing, & analysis platform.",
     "platforms": {

AudioKit/.jazzy.yaml

@@ -13,7 +13,7 @@ custom_categories:
     - AudioKit
     - AKAudioFile
     - AKDevice
-    - AKMicrophoneRecorder
+    - AKMicrophoneTracker
     - AKNodeRecorder
     - AKSettings
     - AKTable
@@ -33,7 +33,6 @@ custom_categories:
     - AKMIDISystemCommand
     - MIDIPacket
     - MIDIPacketList
-    - MIDIPacketListGenerator
     - AKCallbackInstrument
 
   - name: Sequencer
@@ -170,8 +169,8 @@ custom_categories:
     children:
     - AKAudioPlayer
     - AKPhaseLockedVocoder
+    - AKSamplePlayer
     - AKSampler
-    - AKSequencer
     - AKTimePitch
     - AKVariSpeed
 
@@ -212,7 +211,6 @@ custom_categories:
   - name: Random Number Generators
     children:
     - random(_:_:)
-    - randomInt(_:)
 
   - name: Plotting Tools
     children:
@@ -233,7 +231,6 @@ custom_categories:
     - AKBypassButton
     - AKKeyboardView
     - AKKeyboardDelegate
-    - AKNotifications
     - AKPlaygroundLoop
     - AKPlaygroundView
     - AKPresetLoaderView

AudioKit/Common/Internals/AKComponent.swift

@@ -6,10 +6,12 @@
 //  Copyright © 2017 Aurelius Prochazka. All rights reserved.
 //
 
+/// Helpful in reducing repetitive code in AudioKit
 public protocol Aliased {
     associatedtype _Self = Self
 }
 
+/// Helpful in reducing repetitive code in AudioKit
 public protocol AUComponent: class, Aliased {
     static var ComponentDescription: AudioComponentDescription { get }
 }
@@ -22,11 +24,13 @@ extension AUEffect {
     }
 }
 
+/// Helpful in reducing repetitive code in AudioKit
 public protocol AKComponent: AUComponent {
     associatedtype AKAudioUnitType: AnyObject
 }
 
 extension AKComponent {
+    /// Register the audio unit subclass
     public static func register() {
         AUAudioUnit.registerSubclass(Self.AKAudioUnitType.self,
                                      as: Self.ComponentDescription,
@@ -41,7 +45,9 @@ extension AUParameterTree {
     }
 }
 
+/// Adding convenience initializers
 extension AudioComponentDescription {
+    /// Initialize with type and sub-type
     public init(type: OSType, subType: OSType) {
         self.init(componentType: type,
                   componentSubType: subType,
@@ -50,6 +56,7 @@ extension AudioComponentDescription {
                   componentFlagsMask: 0)
     }
 
+    /// Initialize with an Apple effect
     public init(appleEffect subType: OSType) {
         self.init(componentType: kAudioUnitType_Effect,
                   componentSubType: subType,
@@ -58,18 +65,22 @@ extension AudioComponentDescription {
                   componentFlagsMask: 0)
     }
 
+    /// Initialize as an effect with sub-type
     public init(effect subType: OSType) {
         self.init(type: kAudioUnitType_Effect, subType: subType)
     }
 
+    /// Initialize as an effect with sub-type string
     public init(effect subType: String) {
         self.init(effect: fourCC(subType))
     }
 
+    /// Initialize as a mixer with a sub-type string
     public init(mixer subType: String) {
         self.init(type: kAudioUnitType_Mixer, subType: fourCC(subType))
     }
 
+    /// Initialize as a generator with a sub-type string
     public init(generator subType: String) {
         self.init(type: kAudioUnitType_Generator, subType: fourCC(subType))
     }

AudioKit/Common/Internals/AKNodeRecorder.swift

@@ -21,7 +21,7 @@
     /// True if we are recording.
     public private(set) dynamic var isRecording = false
 
-    // An optional duration for the recording to auto-stop when reached
+    /// An optional duration for the recording to auto-stop when reached
     open var durationToRecord: Double = 0
 
     /// Duration of recording
@@ -159,16 +159,15 @@
                 try fileManager.removeItem(atPath: path)
             }
         } catch let error as NSError {
-            AKLog("AKNodeRecorder Error: cannot delete Recording file: \(audioFile?.fileNamePlusExtension ?? "nil")")
-            throw error
+            AKLog("Error: Can't delete: \(audioFile?.fileNamePlusExtension ?? "nil") \(error.localizedDescription)")
         }
 
         // Creates a blank new file
         do {
             internalAudioFile = try AKAudioFile(forWriting: url, settings: settings)
             AKLog("AKNodeRecorder: file has been cleared")
         } catch let error as NSError {
-            AKLog("AKNodeRecorder Error: cannot record to file: \(internalAudioFile.fileNamePlusExtension)")
+            AKLog("Error: Can't record to: \(internalAudioFile.fileNamePlusExtension)")
             throw error
         }
     }

AudioKit/Common/Internals/AKPeriodicFunction.swift

@@ -6,6 +6,7 @@
 //  Copyright © 2017 Aurelius Prochazka. All rights reserved.
 //
 
+/// A class to periodically perform a callback
 public class AKPeriodicFunction: AKOperationGenerator {
     fileprivate var internalHandler: () -> Void = {}
     private var duration = 1.0

AudioKit/Common/Internals/AKSettings.swift

@@ -13,13 +13,29 @@
     /// from Shortest: 2 power 5 samples (32 samples = 0.7 ms @ 44100 kz)
     /// to Longest: 2 power 12 samples (4096 samples = 92.9 ms @ 44100 Hz)
     @objc public enum BufferLength: Int {
+
+        /// Shortest
         case shortest = 5
+
+        /// Very Short
         case veryShort = 6
+
+        /// Short
         case short = 7
+
+        /// Medium
         case medium = 8
+
+        /// Long
         case long = 9
+
+        /// Very Long
         case veryLong = 10
+
+        /// Huge
         case huge = 11
+
+        /// Longest
         case longest = 12
 
         /// The buffer Length expressed as number of samples
@@ -57,7 +73,7 @@
     open static var useBluetooth: Bool = false
 
 #if !os(macOS)
-    // Additional control over the options to use for bluetooth
+    /// Additional control over the options to use for bluetooth
     open static var bluetoothOptions: AVAudioSessionCategoryOptions = []
 #endif
 
@@ -85,7 +101,13 @@
 
     /// Enable AudioKit AVAudioSession Category Management
     open static var disableAVAudioSessionCategoryManagement: Bool = false
-
+
+    // If set to false, AudioKit will not handle the AVAudioSession route change
+    // notification (AVAudioSessionRouteChange) and will not restart the AVAudioEngine
+    // instance when such notifications are posted. The developer can instead subscribe
+    // to these notifications and restart AudioKit after rebuiling their audio chain.
+    open static var enableRouteChangeHandling: Bool = true
+
     /// Turn off AudioKit logging
     open static var enableLogging: Bool = true
 }
@@ -156,8 +178,8 @@ extension AKSettings {
         /// Audio is not silenced by silent switch and screen lock - audio is non mixable. 
         /// To allow mixing see AVAudioSessionCategoryOptionMixWithOthers.
         case playAndRecord
-        /// Disables playback and recording
         #if !os(tvOS)
+        /// Disables playback and recording
         case audioProcessing
         #endif
         /// Use to multi-route audio. May be used on input, output, or both.

AudioKit/Common/Internals/AKTable.swift

@@ -51,6 +51,7 @@ public struct AKTable: MutableCollection {
 
     private var content = [Element]()
 
+    /// Phase of the table
     public var phase: Float {
         didSet {
             phase = (0...1).clamp(phase)
@@ -130,6 +131,7 @@ public struct AKTable: MutableCollection {
         }
     }
 
+    /// Offset of the phase
     public var phaseOffset: Int {
         @inline(__always)
         get {

AudioKit/Common/Internals/Audio File/AKAudioFile.swift

@@ -6,7 +6,10 @@
 //  Copyright © 2017 Aurelius Prochazka. All rights reserved.
 //
 
+/// Adding description property
 extension AVAudioCommonFormat: CustomStringConvertible {
+
+    /// Text version of the format
     public var description: String {
         switch self {
         case .otherFormat:
@@ -23,6 +26,7 @@ extension AVAudioCommonFormat: CustomStringConvertible {
     }
 }
 
+/// Helpful additions for using AVAudioFiles within AudioKit
 extension AVAudioFile {
 
     // MARK: - Public Properties

AudioKit/Common/Internals/AudioKit.h

@@ -110,6 +110,7 @@ FOUNDATION_EXPORT const unsigned char AudioKitVersionString[];
 #import "AKRhodesPianoAudioUnit.h"
 #import "AKShakerAudioUnit.h"
 #import "AKTubularBellsAudioUnit.h"
+#import "AKVocalTractAudioUnit.h"
 
 // Mixing
 #import "AKBalancerAudioUnit.h"

AudioKit/Common/Internals/AudioKit.swift

@@ -14,6 +14,7 @@ import Dispatch
 
 public typealias AKCallback = () -> Void
 
+/// Adding connection between nodes with default format
 extension AVAudioEngine {
     open func connect(_ node1: AVAudioNode, to node2: AVAudioNode) {
         connect(node1, to: node2, format: AudioKit.format)
@@ -218,12 +219,13 @@ extension AVAudioEngine {
             self.engine.prepare()
 
             #if os(iOS)
-
-                NotificationCenter.default.addObserver(
-                    self,
-                    selector: #selector(AudioKit.restartEngineAfterRouteChange),
-                    name: .AVAudioSessionRouteChange,
-                    object: nil)
+                if AKSettings.enableRouteChangeHandling {
+                    NotificationCenter.default.addObserver(
+                        self,
+                        selector: #selector(AudioKit.restartEngineAfterRouteChange),
+                        name: .AVAudioSessionRouteChange,
+                        object: nil)
+                }
             #endif
             #if !os(macOS)
                 if AKSettings.audioInputEnabled {
@@ -381,6 +383,7 @@ extension AVAudioEngine {
 
     // MARK: - Disconnect node inputs
 
+    /// Disconnect all inputs
     @objc open static func disconnectAllInputs() {
         engine.disconnectNodeInput(finalMixer.avAudioNode)
     }

AudioKit/Common/Internals/AudioKitHelpers.swift

@@ -22,6 +22,7 @@ extension Collection where IndexDistance == Int {
         return index(startIndex, offsetBy: offset)
     }
 
+    /// Retrieve a random element from the collection
     public func randomElement() -> Iterator.Element {
         return self[randomIndex]
     }
@@ -246,6 +247,7 @@ internal func AudioUnitSetParameter(_ unit: AudioUnit, param: AudioUnitParameter
     AudioUnitSetParameter(unit, param, kAudioUnitScope_Global, 0, AudioUnitParameterValue(value), 0)
 }
 
+/// Adding subscript
 extension AVAudioUnit {
     subscript (param: AudioUnitParameterID) -> Double {
         get {
@@ -274,6 +276,7 @@ internal struct AUWrapper {
     }
 }
 
+/// Adding instantiation with component and callback
 extension AVAudioUnit {
     class func _instantiate(with component: AudioComponentDescription, callback: @escaping (AVAudioUnit) -> Void) {
         AVAudioUnit.instantiate(with: component, options: []) { avAudioUnit, _ in
@@ -303,6 +306,7 @@ extension AUParameter {
     }
 }
 
+/// Adding instantiate with callback
 extension AudioComponentDescription {
     func instantiate(callback: @escaping (AVAudioUnit) -> Void) {
         AVAudioUnit._instantiate(with: self) {
@@ -337,6 +341,7 @@ extension AVAudioSessionCategoryOptions: Occupiable { }
 
 prefix operator ❗️
 
+/// Negative logic can be confusing, so we draw special attention to those cases
 prefix public func ❗️(a: Bool) -> Bool {
     return !a
 }