add back ability to position waveform vertically when using image API

This is kind of rowing back on 0447737. Intentionally not documented though to avoid the previous confusion
by not promoting its use too much and still leaving it out from the typical use cases inside views.

While views can be moved, the plain image can not, so to avoid the need of further processing, the image
API supports positioning again.

Author: dmrschmidt

Example/DSWaveformImageExample-iOS/ViewController.swift

@@ -72,11 +72,11 @@ class ViewController: UIViewController {
         middleWaveformView.waveformAudioURL = audioURL
 
         Task {
-            let image = try! await waveformImageDrawer.waveformImage(fromAudioAt: audioURL, with: bottomWaveformConfiguration)
+            let image = try! await waveformImageDrawer.waveformImage(fromAudioAt: audioURL, with: bottomWaveformConfiguration, position: .top)
 
             await MainActor.run {
                 // as an added bonus, use CALayer's compositingFilter for more elaborate image display
-                self.bottomWaveformView.layer.compositingFilter = "multiplyBlendMode"
+                self.bottomWaveformView.layer.compositingFilter = "overlayBlendMode"
                 self.bottomWaveformView.image = image
             }
         }
@@ -89,7 +89,7 @@ class ViewController: UIViewController {
     private var bottomWaveformConfiguration: Waveform.Configuration {
         Waveform.Configuration(
             size: bottomWaveformView.bounds.size,
-            style: .filled(UIColor(red: 129/255.0, green: 178/255.0, blue: 154/255.0, alpha: 1))
+            style: .filled(.black)
         )
     }
 }

Sources/DSWaveformImage/Renderers/CircularWaveformRenderer.swift

@@ -25,14 +25,14 @@ public struct CircularWaveformRenderer: WaveformRenderer {
         self.kind = kind
     }
 
-    public func path(samples: [Float], with configuration: Waveform.Configuration, lastOffset: Int) -> CGPath {
+    public func path(samples: [Float], with configuration: Waveform.Configuration, lastOffset: Int, position: Waveform.Position = .middle) -> CGPath {
         switch kind {
-        case .circle: return circlePath(samples: samples, with: configuration, lastOffset: lastOffset)
-        case .ring: return ringPath(samples: samples, with: configuration, lastOffset: lastOffset)
+        case .circle: return circlePath(samples: samples, with: configuration, lastOffset: lastOffset, position: position)
+        case .ring: return ringPath(samples: samples, with: configuration, lastOffset: lastOffset, position: position)
         }
     }
 
-    public func render(samples: [Float], on context: CGContext, with configuration: Waveform.Configuration, lastOffset: Int) {
+    public func render(samples: [Float], on context: CGContext, with configuration: Waveform.Configuration, lastOffset: Int, position: Waveform.Position = .middle) {
         let path = path(samples: samples, with: configuration, lastOffset: lastOffset)
         context.addPath(path)
 
@@ -54,10 +54,13 @@ public struct CircularWaveformRenderer: WaveformRenderer {
         }
     }
 
-    private func circlePath(samples: [Float], with configuration: Waveform.Configuration, lastOffset: Int) -> CGPath {
+    private func circlePath(samples: [Float], with configuration: Waveform.Configuration, lastOffset: Int, position: Waveform.Position) -> CGPath {
         let graphRect = CGRect(origin: .zero, size: configuration.size)
         let maxRadius = CGFloat(min(graphRect.maxX, graphRect.maxY) / 2.0) * configuration.verticalScalingFactor
-        let center = CGPoint(x: graphRect.maxX * 0.5, y: graphRect.maxY * 0.5)
+        let center = CGPoint(
+            x: graphRect.maxX * position.offset(),
+            y: graphRect.maxY * position.offset()
+        )
         let path = CGMutablePath()
 
         path.move(to: center)
@@ -86,15 +89,18 @@ public struct CircularWaveformRenderer: WaveformRenderer {
         return path
     }
 
-    private func ringPath(samples: [Float], with configuration: Waveform.Configuration, lastOffset: Int) -> CGPath {
+    private func ringPath(samples: [Float], with configuration: Waveform.Configuration, lastOffset: Int, position: Waveform.Position) -> CGPath {
         guard case let .ring(config) = kind else {
             fatalError("called with wrong kind")
         }
 
         let graphRect = CGRect(origin: .zero, size: configuration.size)
         let maxRadius = CGFloat(min(graphRect.maxX, graphRect.maxY) / 2.0) * configuration.verticalScalingFactor
         let innerRadius: CGFloat = maxRadius * config
-        let center = CGPoint(x: graphRect.maxX * 0.5, y: graphRect.maxY * 0.5)
+        let center = CGPoint(
+            x: graphRect.maxX * position.offset(),
+            y: graphRect.maxY * position.offset()
+        )
         let path = CGMutablePath()
 
         path.move(to: CGPoint(

Sources/DSWaveformImage/Renderers/LinearWaveformRenderer.swift

@@ -9,26 +9,26 @@ import CoreGraphics
 public struct LinearWaveformRenderer: WaveformRenderer {
     public init() {}
 
-    public func path(samples: [Float], with configuration: Waveform.Configuration, lastOffset: Int) -> CGPath {
+    public func path(samples: [Float], with configuration: Waveform.Configuration, lastOffset: Int, position: Waveform.Position = .middle) -> CGPath {
         let graphRect = CGRect(origin: CGPoint.zero, size: configuration.size)
-        let positionAdjustedGraphCenter = 0.5 * graphRect.size.height
+        let positionAdjustedGraphCenter = position.offset() * graphRect.size.height
         var path = CGMutablePath()
 
         path.move(to: CGPoint(x: 0, y: positionAdjustedGraphCenter))
 
         if case .striped = configuration.style {
-            path = draw(samples: samples, path: path, with: configuration, lastOffset: lastOffset, sides: .both)
+            path = draw(samples: samples, path: path, with: configuration, lastOffset: lastOffset, sides: .both, position: position)
         } else {
-            path = draw(samples: samples, path: path, with: configuration, lastOffset: lastOffset, sides: .up)
-            path = draw(samples: samples.reversed(), path: path, with: configuration, lastOffset: lastOffset, sides: .down)
+            path = draw(samples: samples, path: path, with: configuration, lastOffset: lastOffset, sides: .up, position: position)
+            path = draw(samples: samples.reversed(), path: path, with: configuration, lastOffset: lastOffset, sides: .down, position: position)
         }
 
         path.closeSubpath()
         return path
     }
 
-    public func render(samples: [Float], on context: CGContext, with configuration: Waveform.Configuration, lastOffset: Int) {
-        context.addPath(path(samples: samples, with: configuration, lastOffset: lastOffset))
+    public func render(samples: [Float], on context: CGContext, with configuration: Waveform.Configuration, lastOffset: Int, position: Waveform.Position = .middle) {
+        context.addPath(path(samples: samples, with: configuration, lastOffset: lastOffset, position: position))
         defaultStyle(context: context, with: configuration)
     }
 
@@ -44,10 +44,10 @@ public struct LinearWaveformRenderer: WaveformRenderer {
         case up, down, both
     }
 
-    private func draw(samples: [Float], path: CGMutablePath, with configuration: Waveform.Configuration, lastOffset: Int, sides: Sides) -> CGMutablePath {
+    private func draw(samples: [Float], path: CGMutablePath, with configuration: Waveform.Configuration, lastOffset: Int, sides: Sides, position: Waveform.Position = .middle) -> CGMutablePath {
         let graphRect = CGRect(origin: CGPoint.zero, size: configuration.size)
-        let positionAdjustedGraphCenter = 0.5 * graphRect.size.height
-        let drawMappingFactor = 0.5 * graphRect.size.height * configuration.verticalScalingFactor // we always draw in the center now
+        let positionAdjustedGraphCenter = position.offset() * graphRect.size.height
+        let drawMappingFactor = graphRect.size.height * configuration.verticalScalingFactor
         let minimumGraphAmplitude: CGFloat = 1 / configuration.scale // we want to see at least a 1px line for silence
         var maxAmplitude: CGFloat = 0.0 // we know 1 is our max in normalized data, but we keep it 'generic'
 

Sources/DSWaveformImage/WaveformImageDrawer+iOS.swift

@@ -8,7 +8,7 @@ public extension WaveformImageDrawer {
     /// Renders a DSImage of the provided waveform samples.
     ///
     /// Samples need to be normalized within interval `(0...1)`.
-    func waveformImage(from samples: [Float], with configuration: Waveform.Configuration, renderer: WaveformRenderer) -> DSImage? {
+    func waveformImage(from samples: [Float], with configuration: Waveform.Configuration, renderer: WaveformRenderer, position: Waveform.Position = .middle) -> DSImage? {
         guard samples.count > 0, samples.count == Int(configuration.size.width * configuration.scale) else {
             print("ERROR: samples: \(samples.count) != \(configuration.size.width) * \(configuration.scale)")
             return nil
@@ -20,7 +20,7 @@ public extension WaveformImageDrawer {
         let dampedSamples = configuration.shouldDamp ? damp(samples, with: configuration) : samples
 
         return imageRenderer.image { renderContext in
-            draw(on: renderContext.cgContext, from: dampedSamples, with: configuration, renderer: renderer)
+            draw(on: renderContext.cgContext, from: dampedSamples, with: configuration, renderer: renderer, position: position)
         }
     }
 }

Sources/DSWaveformImage/WaveformImageDrawer.swift

@@ -27,8 +27,9 @@ public class WaveformImageDrawer: ObservableObject {
     public func waveformImage(fromAudioAt audioAssetURL: URL,
                               with configuration: Waveform.Configuration,
                               renderer: WaveformRenderer = LinearWaveformRenderer(),
+                              position: Waveform.Position = .middle,
                               qos: DispatchQoS.QoSClass = .userInitiated) async throws -> DSImage {
-        try await render(fromAudioAt: audioAssetURL, with: configuration, renderer: renderer, qos: qos)
+        try await render(fromAudioAt: audioAssetURL, with: configuration, renderer: renderer, qos: qos, position: position)
     }
 
     /// Async analyzes the provided audio and renders a DSImage of the waveform data calculated by the analyzer.
@@ -44,10 +45,11 @@ public class WaveformImageDrawer: ObservableObject {
                               with configuration: Waveform.Configuration,
                               renderer: WaveformRenderer = LinearWaveformRenderer(),
                               qos: DispatchQoS.QoSClass = .userInitiated,
+                              position: Waveform.Position = .middle,
                               completionHandler: @escaping (Result<DSImage, Error>) -> ()) {
         Task {
             do {
-                let image = try await render(fromAudioAt: audioAssetURL, with: configuration, renderer: renderer, qos: qos)
+                let image = try await render(fromAudioAt: audioAssetURL, with: configuration, renderer: renderer, qos: qos, position: position)
                 completionHandler(.success(image))
             } catch {
                 completionHandler(.failure(error))
@@ -96,13 +98,13 @@ extension WaveformImageDrawer {
         draw(on: context, from: paddedSamples, with: configuration, renderer: renderer)
     }
 
-    func draw(on context: CGContext, from samples: [Float], with configuration: Waveform.Configuration, renderer: WaveformRenderer) {
+    func draw(on context: CGContext, from samples: [Float], with configuration: Waveform.Configuration, renderer: WaveformRenderer, position: Waveform.Position = .middle) {
         context.setAllowsAntialiasing(configuration.shouldAntialias)
         context.setShouldAntialias(configuration.shouldAntialias)
         context.setAlpha(1.0)
 
         drawBackground(on: context, with: configuration)
-        renderer.render(samples: samples, on: context, with: configuration, lastOffset: lastOffset)
+        renderer.render(samples: samples, on: context, with: configuration, lastOffset: lastOffset, position: position)
     }
 
     /// Damp the samples for a smoother animation.
@@ -125,14 +127,15 @@ private extension WaveformImageDrawer {
         fromAudioAt audioAssetURL: URL,
         with configuration: Waveform.Configuration,
         renderer: WaveformRenderer,
-        qos: DispatchQoS.QoSClass
+        qos: DispatchQoS.QoSClass,
+        position: Waveform.Position
     ) async throws -> DSImage {
         let sampleCount = Int(configuration.size.width * configuration.scale)
         let waveformAnalyzer = WaveformAnalyzer()
         let samples = try await waveformAnalyzer.samples(fromAudioAt: audioAssetURL, count: sampleCount, qos: qos)
         let dampedSamples = configuration.shouldDamp ? self.damp(samples, with: configuration) : samples
 
-        if let image = waveformImage(from: dampedSamples, with: configuration, renderer: renderer) {
+        if let image = waveformImage(from: dampedSamples, with: configuration, renderer: renderer, position: position) {
             return image
         } else {
             throw GenerationError.generic

Sources/DSWaveformImage/WaveformImageTypes.swift

@@ -41,7 +41,7 @@ public protocol WaveformRenderer: Sendable {
         - lastOffset: You can typtically leave this `0`. **Required for live rendering**, where it is needed to keep track of the last drawing cycle. Setting it avoids 'flickering' as samples are being added
          continuously and the waveform moves across the view.
      */
-    func path(samples: [Float], with configuration: Waveform.Configuration, lastOffset: Int) -> CGPath
+    func path(samples: [Float], with configuration: Waveform.Configuration, lastOffset: Int, position: Waveform.Position) -> CGPath
 
     /**
      Renders the waveform samples  on the provided `CGContext`.
@@ -53,10 +53,45 @@ public protocol WaveformRenderer: Sendable {
         - lastOffset: You can typtically leave this `0`. **Required for live rendering**, where it is needed to keep track of the last drawing cycle. Setting it avoids 'flickering' as samples are being added
          continuously and the waveform moves across the view.
      */
-    func render(samples: [Float], on context: CGContext, with configuration: Waveform.Configuration, lastOffset: Int)
+    func render(samples: [Float], on context: CGContext, with configuration: Waveform.Configuration, lastOffset: Int, position: Waveform.Position)
+}
+
+public extension WaveformRenderer {
+    func path(samples: [Float], with configuration: Waveform.Configuration, lastOffset: Int, position: Waveform.Position = .middle) -> CGPath {
+        path(samples: samples, with: configuration, lastOffset: lastOffset, position: position)
+    }
+
+    func render(samples: [Float], on context: CGContext, with configuration: Waveform.Configuration, lastOffset: Int, position: Waveform.Position = .middle) {
+        render(samples: samples, on: context, with: configuration, lastOffset: lastOffset, position: position)
+    }
 }
 
 public enum Waveform {
+    /** Position of the drawn waveform. */
+     public enum Position: Equatable {
+         /// **top**: Draws the waveform at the top of the image, such that only the bottom 50% are visible.
+         case top
+
+         /// **middle**: Draws the waveform in the middle the image, such that the entire waveform is visible.
+         case middle
+
+         /// **bottom**: Draws the waveform at the bottom of the image, such that only the top 50% are visible.
+         case bottom
+
+         /// **custom**: Draws the waveform at the specified point of the image. Clamped within range `(0...1)`. Where `0`
+         ///  is equal to `.top`, `0.5` is equal to `.middle` and `1` is equal to `.bottom`.
+         case custom(CGFloat)
+
+         func offset() -> CGFloat {
+             switch self {
+             case .top: return 0.0
+             case .middle: return 0.5
+             case .bottom: return 1.0
+             case let .custom(offset): return min(1, max(0, offset))
+             }
+         }
+     }
+
     /**
      Style of the waveform which is used during drawing:
      - **filled**: Use solid color for the waveform.