Release 2.12.0

Co-Authored-By: fayinsky <38639193+fayinsky@users.noreply.github.com>

Example/Pods/Pods.xcodeproj/project.xcworkspace/contents.xcworkspacedata

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Workspace
+   version = "1.0">
+   <FileRef
+      location = "self:">
+   </FileRef>
+</Workspace>

Example/Pods/Pods.xcodeproj/project.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>IDEDidComputeMac32BitWarning</key>
+	<true/>
+</dict>
+</plist>

Example/SwiftAudioPlayer/ViewController.swift

@@ -103,6 +103,8 @@ class ViewController: UIViewController {
     override func viewDidLoad() {
         super.viewDidLoad()
         
+        SAPlayer.Downloader.allowUsingCellularData = true
+        
         SAPlayer.shared.DEBUG_MODE = true
         
         isPlayable = false

README.md

@@ -34,6 +34,11 @@ pod 'SwiftAudioPlayer'
 
 ### Usage
 
+Import the player at the top:
+```swift
+import SwiftAudioPlayer
+```
+
 **Important:** For app in background downloading please refer to [note](#important-step-for-background-downloads).
 
 To play remote audio:
@@ -118,6 +123,10 @@ SwiftAudioPlayer is available under the MIT license. See the LICENSE file for mo
 
 Access the player and all of its fields and functions through `SAPlayer.shared`.
 
+### Supported file types
+
+Known supported file types are `.mp3` and `.wav`.
+
 ### Playing Audio (Basic Commands)
 
 To set up player with audio to play, use either: 
@@ -194,6 +203,12 @@ And use the following to stop any active or prevent future downloads of the corr
 func cancelDownload(withRemoteUrl url: URL)
 ```
 
+By default downloading will be allowed on cellular data. If you would like to turn this off set:
+```swift
+SAPlayer.Downloader.allowUsingCellularData = false
+```
+You can also retrieve what preference you have set for cellular downloads through `allowUsingCellularData`.
+
 ### Manage Downloaded
 
 Use the following to manage downloaded audio files.

Source/Engine/AudioStreamEngine.swift

@@ -290,6 +290,16 @@ class AudioStreamEngine: AudioEngine {
         updateNetworkBufferRange()
     }
     
+    override func pause() {
+        queue.async { [weak self] in
+            self?.pauseHelperDispatchQueue()
+        }
+    }
+    
+    private func pauseHelperDispatchQueue() {
+        super.pause()
+    }
+    
     override func invalidate() {
         super.invalidate()
         converter.invalidate()

Source/Engine/Converter/AudioConverterErrors.swift

@@ -83,7 +83,7 @@ public enum ConverterError: LocalizedError {
             Log.warn("Weird unexpected reader error. Should not have happened")
             return "Weird unexpected reader error. Should not have happened"
         case .cannotCreatePCMBufferWithoutConverter:
-            Log.warn("Could not create a PCM Buffer because reader does not have a converter yet")
+            Log.debug("Could not create a PCM Buffer because reader does not have a converter yet")
             return "Could not create a PCM Buffer because reader does not have a converter yet"
         case .throttleParsingBuffersForEngine:
             Log.warn("Preventing the reader from creating more PCM buffers since the player has more than 60 seconds of audio already to play")

Source/Model/AudioDataManager.swift

@@ -32,6 +32,7 @@ protocol AudioDataManagable {
     var allowCellular: Bool { get set }
     
     func setBackgroundCompletionHandler(_ completionHandler: @escaping () -> ())
+    func setAllowCellularDownloadPreference(_ preference: Bool)
     
     func clear()
     
@@ -51,7 +52,7 @@ protocol AudioDataManagable {
 }
 
 class AudioDataManager: AudioDataManagable {
-    var allowCellular: Bool = false
+    var allowCellular: Bool = true
     
     static let shared: AudioDataManagable = AudioDataManager()
     
@@ -99,6 +100,10 @@ class AudioDataManager: AudioDataManagable {
         backgroundCompletion = completionHandler
     }
     
+    func setAllowCellularDownloadPreference(_ preference: Bool) {
+        allowCellular = preference
+    }
+    
     func attach(callback: @escaping (_ id: ID, _ progress: Double)->()) {
         globalDownloadProgressCallback = callback
     }

Source/Model/Downloading/FileStorage.swift

@@ -103,12 +103,15 @@ extension FileStorage {
         }
         
         static func locate(_ id: ID) -> URL? {
-            let urls = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)
-            
-            for url in urls {
-                if url.absoluteString.contains(id) && url.pathExtension != "" {
-                    _ = getUrl(givenId: id, andFileExtension: url.pathExtension)
-                    return url
+            let folderUrls = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)
+            guard folderUrls.count != 0 else { return nil }
+
+            if let urls = try? FileManager.default.contentsOfDirectory(at: folderUrls[0], includingPropertiesForKeys: nil) {
+                for url in urls {
+                    if url.absoluteString.contains(id) && url.pathExtension != "" {
+                        _ = getUrl(givenId: id, andFileExtension: url.pathExtension)
+                        return url
+                    }
                 }
             }
             return nil

Source/SAPlayer.swift

@@ -56,6 +56,17 @@ public class SAPlayer {
         }
     }
     
+    /**
+    Access the player node of the engine. Node is nil if player has not been initialized with audio.
+     
+     - Important: Changes to the engine and this node are not safe guarded, thus unknown behaviour can arise from changing the engine or this node. Just be wary and read [documentation of AVAudioEngine](https://developer.apple.com/documentation/avfoundation/avaudioengine) well when modifying,
+    */
+    public var playerNode: AVAudioPlayerNode? {
+        get {
+            return player?.playerNode
+        }
+    }
+    
     /**
     Corresponding to the overall volume of the player. Volume's default value is 1.0 and the range of valid values is 0.0 to 1.0. Volume is nil if no audio has been initialized yet.
     */
@@ -109,6 +120,10 @@ public class SAPlayer {
          }
          ````
          Please look at [forums.developer.apple.com/thread/5874](https://forums.developer.apple.com/thread/5874) and [forums.developer.apple.com/thread/6050](https://forums.developer.apple.com/thread/6050) for more details.
+     
+     For more details on pitch modifiers for playback rate changes please look at [developer.apple.com/forums/thread/6050](https://developer.apple.com/forums/thread/6050).
+     
+     To remove this default pitch modifier for playback rate changes, remove the node by calling `SAPlayer.shared.clearAudioModifiers()`.
      */
     public var audioModifiers: [AVAudioUnit] = []
     
@@ -181,6 +196,22 @@ public class SAPlayer {
         audioModifiers.append(AVAudioUnitTimePitch(audioComponentDescription: componentDescription))
     }
     
+    /**
+     Clears all [AVAudioUnit](https://developer.apple.com/documentation/avfoundation/audio_track_engineering/audio_engine_building_blocks/audio_enhancements) modifiers intended to be used for realtime audio manipulation.
+     */
+    public func clearAudioModifiers() {
+        audioModifiers.removeAll()
+    }
+    
+    /**
+     Append an [AVAudioUnit](https://developer.apple.com/documentation/avfoundation/audio_track_engineering/audio_engine_building_blocks/audio_enhancements) modifier to the list of modifiers used for realtime audio manipulation. The modifier will be added to the end of the list.
+
+     - Parameter modifier: The modifier to append.
+     */
+    public func addAudioModifier(_ modifer: AVAudioUnit) {
+        audioModifiers.append(modifer)
+    }
+    
     /**
      Formats a textual representation of a given timestamp for display in hh:MM:SS format, that is hours:minutes:seconds.
 
@@ -266,6 +297,23 @@ extension SAPlayer {
     /**
      If using an AVAudioUnitTimePitch, it's important to notify the player that the rate at which the audio playing has changed to keep the media player in the lockscreen up to date. This is only important for playback rate changes.
      
+     - Note: By default this engine has added a pitch modifier node to change the pitch so that on playback rate changes of spoken word the pitch isn't shifted.
+     
+     The component description of this node is:
+     ````
+     var componentDescription: AudioComponentDescription {
+        get {
+            var ret = AudioComponentDescription()
+            ret.componentType = kAudioUnitType_FormatConverter
+            ret.componentSubType = kAudioUnitSubType_AUiPodTimeOther
+            return ret
+        }
+     }
+     ````
+     Please look at [forums.developer.apple.com/thread/5874](https://forums.developer.apple.com/thread/5874) and [forums.developer.apple.com/thread/6050](https://forums.developer.apple.com/thread/6050) for more details.
+     
+     For more details on pitch modifiers for playback rate changes please look at [developer.apple.com/forums/thread/6050](https://developer.apple.com/forums/thread/6050).
+     
      - Parameter rate: The current rate at which the audio is playing.
      */
     public func playbackRateOfAudioChanged(rate: Float) {
@@ -277,6 +325,23 @@ extension SAPlayer {
      
      - Important: If intending to use [AVAudioUnit](https://developer.apple.com/documentation/avfoundation/audio_track_engineering/audio_engine_building_blocks/audio_enhancements) audio modifiers during playback, the list of audio modifiers under `SAPlayer.shared.audioModifiers` must be finalized before calling this function. After all realtime audio manipulations within the this will be effective.
      
+     - Note: The default list already has an AVAudioUnitTimePitch node first in the list. This node is specifically set to change the rate of audio without changing the pitch of the audio (intended for changing the rate of spoken word).
+     
+         The component description of this node is:
+         ````
+         var componentDescription: AudioComponentDescription {
+            get {
+                var ret = AudioComponentDescription()
+                ret.componentType = kAudioUnitType_FormatConverter
+                ret.componentSubType = kAudioUnitSubType_AUiPodTimeOther
+                return ret
+            }
+         }
+         ````
+         Please look at [forums.developer.apple.com/thread/5874](https://forums.developer.apple.com/thread/5874) and [forums.developer.apple.com/thread/6050](https://forums.developer.apple.com/thread/6050) for more details.
+     
+     To remove this default pitch modifier for playback rate changes, remove the node by calling `SAPlayer.shared.clearAudioModifiers()`.
+     
      - Parameter withSavedUrl: The URL of the audio saved on the device.
      - Parameter mediaInfo: The media information of the audio to show on the lockscreen media player (optional).
      */
@@ -296,6 +361,23 @@ extension SAPlayer {
      
      - Important: If intending to use [AVAudioUnit](https://developer.apple.com/documentation/avfoundation/audio_track_engineering/audio_engine_building_blocks/audio_enhancements) audio modifiers during playback, the list of audio modifiers under `SAPlayer.shared.audioModifiers` must be finalized before calling this function. After all realtime audio manipulations within the this will be effective.
      
+     - Note: The default list already has an AVAudioUnitTimePitch node first in the list. This node is specifically set to change the rate of audio without changing the pitch of the audio (intended for changing the rate of spoken word).
+     
+         The component description of this node is:
+         ````
+         var componentDescription: AudioComponentDescription {
+            get {
+                var ret = AudioComponentDescription()
+                ret.componentType = kAudioUnitType_FormatConverter
+                ret.componentSubType = kAudioUnitSubType_AUiPodTimeOther
+                return ret
+            }
+         }
+         ````
+         Please look at [forums.developer.apple.com/thread/5874](https://forums.developer.apple.com/thread/5874) and [forums.developer.apple.com/thread/6050](https://forums.developer.apple.com/thread/6050) for more details.
+     
+     To remove this default pitch modifier for playback rate changes, remove the node by calling `SAPlayer.shared.clearAudioModifiers()`.
+     
      - Note: Subscribe to `SAPlayer.Updates.StreamingBuffer` to see updates in streaming progress.
      
      - Parameter withRemoteUrl: The URL of the remote audio.

Source/SAPlayerDownloader.swift

@@ -100,5 +100,14 @@ extension SAPlayer {
         public static func setBackgroundCompletionHandler(_ completionHandler: @escaping () -> ()) {
             AudioDataManager.shared.setBackgroundCompletionHandler(completionHandler)
         }
+        
+        /**
+         Whether downloading audio on cellular data is allowed. By default this is set to `true`.
+         */
+        public static var allowUsingCellularData = true {
+            didSet {
+                AudioDataManager.shared.setAllowCellularDownloadPreference(allowUsingCellularData)
+            }
+        }
     }
 }

SwiftAudioPlayer.podspec

@@ -8,7 +8,7 @@
 
 Pod::Spec.new do |s|
   s.name             = 'SwiftAudioPlayer'
-  s.version          = '2.10.0'
+  s.version          = '2.12.0'
   s.summary          = 'SwiftAudioPlayer is a Swift based audio player that can handle streaming from a remote location and audio manipulation.'
 
 # This description is used to generate tags and improve search results.