react-native-waveform-player 0.0.1 → 1.0.0

package/ios/AudioPlayerEngine.swift

@@ -0,0 +1,281 @@
+import AVFoundation
+import Foundation
+import UIKit
+
+/// Thin wrapper around `AVPlayer` that exposes the events the rest of the
+/// component needs: load lifecycle, periodic time updates, end-of-track,
+/// and rate / seek control. All callbacks fire on the main thread.
+final class AudioPlayerEngine {
+
+    // MARK: - State
+
+    enum State {
+        case idle
+        case loading
+        case ready
+        case ended
+        case error
+    }
+
+    private(set) var state: State = .idle {
+        didSet {
+            guard oldValue != state else { return }
+            // If the user tapped "play" while we were still loading, apply
+            // playback synchronously *before* firing onStateChange so the
+            // single notification reflects the final state (state == .ready
+            // AND isPlaying == true). Without this we'd fire one event with
+            // isPlaying=false (causing a brief play-icon flash) then a
+            // second one once startInternal flips it.
+            if state == .ready, pendingStart {
+                pendingStart = false
+                startPlaybackInternal()
+            }
+            onStateChange?()
+        }
+    }
+
+    /// "Play once ready" intent recorded during the `.loading` state.
+    /// Cleared on pause / reset / source change.
+    private var pendingStart: Bool = false
+
+    private(set) var durationMs: Int = 0
+    private(set) var currentMs: Int = 0
+    /// `true` while the engine is in a "playing" state from the user's POV
+    /// (i.e. `play()` was called and we haven't been paused or ended).
+    /// We track this explicitly because `AVPlayer.timeControlStatus` flips
+    /// between `playing` / `waitingToPlayAtSpecifiedRate` during buffering.
+    private(set) var isPlaying: Bool = false
+    private(set) var rate: Float = 1.0
+    var loop: Bool = false
+
+    // MARK: - Callbacks
+
+    var onLoad: ((Int) -> Void)?
+    var onLoadError: ((String) -> Void)?
+    var onStateChange: (() -> Void)?
+    var onTimeUpdate: ((Int, Int) -> Void)?
+    var onEnded: (() -> Void)?
+
+    // MARK: - Private
+
+    private let player = AVPlayer()
+    private var currentItem: AVPlayerItem?
+    private var timeObserver: Any?
+    private var statusObservation: NSKeyValueObservation?
+    private var endObservation: NSObjectProtocol?
+
+    init() {
+        player.actionAtItemEnd = .pause
+        // Be eager about playback readiness: AVPlayer's default behaviour
+        // is to accumulate a generous forward buffer before flipping
+        // `.readyToPlay`, which can keep the loading spinner on screen
+        // for many seconds even after enough data has arrived to start
+        // playback. With this disabled, `.readyToPlay` fires as soon as
+        // the item has decodable samples queued up.
+        player.automaticallyWaitsToMinimizeStalling = false
+        // The library does not configure AVAudioSession by default to avoid
+        // surprises; opt-in via `setBackgroundPlaybackEnabled(true)` instead.
+    }
+
+    /// Configure the shared `AVAudioSession` so audio keeps playing when the
+    /// host app is backgrounded. Requires the host app to have the "Audio,
+    /// AirPlay, and Picture in Picture" Background Mode enabled in Info.plist.
+    ///
+    /// Calling with `false` is a no-op — once the session category has been
+    /// switched to `.playback` we leave it alone (the host app may have its
+    /// own audio session management we don't want to step on).
+    func setBackgroundPlaybackEnabled(_ enabled: Bool) {
+        guard enabled else { return }
+        let session = AVAudioSession.sharedInstance()
+        // Don't churn the session if it's already in a playback-capable mode.
+        if session.category == .playback || session.category == .playAndRecord {
+            try? session.setActive(true, options: [])
+            return
+        }
+        do {
+            try session.setCategory(.playback, mode: .default, options: [])
+            try session.setActive(true, options: [])
+        } catch {
+            // Silently ignore — host app likely manages its own session.
+        }
+    }
+
+    deinit {
+        teardownObservers()
+    }
+
+    // MARK: - Public API
+
+    func setSource(url: URL) {
+        teardownObservers()
+
+        pendingStart = false
+        state = .loading
+        currentMs = 0
+        durationMs = 0
+
+        let item = AVPlayerItem(url: url)
+        currentItem = item
+        statusObservation = item.observe(\.status, options: [.new]) { [weak self] item, _ in
+            guard let self = self else { return }
+            DispatchQueue.main.async {
+                switch item.status {
+                case .readyToPlay:
+                    let durSeconds = item.duration.seconds
+                    if durSeconds.isFinite, durSeconds > 0 {
+                        self.durationMs = Int(durSeconds * 1000)
+                    } else {
+                        self.durationMs = 0
+                    }
+                    self.state = .ready
+                    self.onLoad?(self.durationMs)
+                case .failed:
+                    let message = item.error?.localizedDescription ?? "Unknown player error"
+                    self.state = .error
+                    self.onLoadError?(message)
+                default:
+                    break
+                }
+            }
+        }
+
+        endObservation = NotificationCenter.default.addObserver(
+            forName: .AVPlayerItemDidPlayToEndTime,
+            object: item,
+            queue: .main
+        ) { [weak self] _ in
+            self?.handleEnd()
+        }
+
+        player.replaceCurrentItem(with: item)
+
+        let interval = CMTime(value: 1, timescale: 30)
+        timeObserver = player.addPeriodicTimeObserver(
+            forInterval: interval,
+            queue: .main
+        ) { [weak self] time in
+            guard let self = self, self.durationMs > 0 else { return }
+            let seconds = time.seconds
+            if seconds.isFinite, seconds >= 0 {
+                self.currentMs = min(self.durationMs, Int(seconds * 1000))
+                self.onTimeUpdate?(self.currentMs, self.durationMs)
+            }
+        }
+    }
+
+    func play() {
+        if state == .loading {
+            // Audio isn't buffered yet — record the intent and let the
+            // state setter resume playback the instant we transition to
+            // `.ready`. We deliberately don't fire onStateChange here so
+            // the play/pause button stays as the loading spinner instead
+            // of briefly flipping to a "pause" icon while still loading.
+            pendingStart = true
+            return
+        }
+        guard state == .ready || state == .ended else { return }
+        // Already running — skip so we don't fire a redundant
+        // onStateChange every time `applyControlledState()` is called.
+        if isPlaying && state == .ready { return }
+        // Clear any stale pending intent before we drive state changes,
+        // so the state-setter doesn't try to "resume" again.
+        pendingStart = false
+        if state == .ended {
+            player.seek(to: .zero)
+            currentMs = 0
+            state = .ready
+        }
+        startPlaybackInternal()
+        onStateChange?()
+    }
+
+    func pause() {
+        // Cancel any queued "play once ready" intent — the user explicitly
+        // wants playback to stay paused.
+        pendingStart = false
+        guard isPlaying else { return }
+        isPlaying = false
+        player.pause()
+        onStateChange?()
+    }
+
+    func toggle() {
+        if isPlaying { pause() } else { play() }
+    }
+
+    /// Seek to position in milliseconds. Uses an exact-tolerance seek so the
+    /// playhead lands on the requested sample even for VBR mp3.
+    func seek(toMs ms: Int, completion: (() -> Void)? = nil) {
+        let clamped = max(0, min(durationMs, ms))
+        currentMs = clamped
+        let target = CMTime(value: CMTimeValue(clamped), timescale: 1000)
+        player.seek(to: target, toleranceBefore: .zero, toleranceAfter: .zero) { _ in
+            completion?()
+        }
+    }
+
+    func setRate(_ newRate: Float) {
+        let clamped = max(0.25, min(4.0, newRate))
+        rate = clamped
+        if isPlaying {
+            player.rate = clamped
+        }
+    }
+
+    func reset() {
+        pendingStart = false
+        teardownObservers()
+        player.replaceCurrentItem(with: nil)
+        currentItem = nil
+        isPlaying = false
+        currentMs = 0
+        durationMs = 0
+        state = .idle
+    }
+
+    // MARK: - Internal
+
+    /// Common play-start sequence shared by `play()` and the in-line
+    /// resume from the `state` setter when transitioning to `.ready`
+    /// with a queued tap intent. Does NOT fire `onStateChange` — callers
+    /// are responsible for that (so we can batch a single notification).
+    private func startPlaybackInternal() {
+        isPlaying = true
+        player.rate = rate
+        // Calling `player.play()` after setting rate keeps the rate sticky
+        // even after a previous .pause() reset it to 0.
+        player.play()
+        player.rate = rate
+    }
+
+    private func handleEnd() {
+        if loop {
+            player.seek(to: .zero)
+            currentMs = 0
+            if isPlaying {
+                player.rate = rate
+                player.play()
+                player.rate = rate
+            }
+        } else {
+            isPlaying = false
+            currentMs = durationMs
+            state = .ended
+            onTimeUpdate?(currentMs, durationMs)
+            onEnded?()
+        }
+    }
+
+    private func teardownObservers() {
+        if let timeObserver = timeObserver {
+            player.removeTimeObserver(timeObserver)
+        }
+        timeObserver = nil
+        statusObservation?.invalidate()
+        statusObservation = nil
+        if let endObservation = endObservation {
+            NotificationCenter.default.removeObserver(endObservation)
+        }
+        endObservation = nil
+    }
+}

package/ios/AudioWaveformView.h

@@ -0,0 +1,14 @@
+#import <React/RCTViewComponentView.h>
+#import <UIKit/UIKit.h>
+
+#ifndef AudioWaveformViewNativeComponent_h
+#define AudioWaveformViewNativeComponent_h
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface AudioWaveformView : RCTViewComponentView
+@end
+
+NS_ASSUME_NONNULL_END
+
+#endif /* AudioWaveformViewNativeComponent_h */

package/ios/AudioWaveformView.mm

@@ -0,0 +1,307 @@
+#import "AudioWaveformView.h"
+
+#import <React/RCTConversions.h>
+
+#import <react/renderer/components/AudioWaveformViewSpec/ComponentDescriptors.h>
+#import <react/renderer/components/AudioWaveformViewSpec/EventEmitters.h>
+#import <react/renderer/components/AudioWaveformViewSpec/Props.h>
+#import <react/renderer/components/AudioWaveformViewSpec/RCTComponentViewHelpers.h>
+
+#import "RCTFabricComponentsPlugins.h"
+
+#if __has_include(<AudioWaveform/AudioWaveform-Swift.h>)
+#import <AudioWaveform/AudioWaveform-Swift.h>
+#else
+#import "AudioWaveform-Swift.h"
+#endif
+
+using namespace facebook::react;
+
+@implementation AudioWaveformView {
+  AudioWaveformViewImpl *_impl;
+}
+
++ (ComponentDescriptorProvider)componentDescriptorProvider
+{
+  return concreteComponentDescriptorProvider<AudioWaveformViewComponentDescriptor>();
+}
+
+- (instancetype)initWithFrame:(CGRect)frame
+{
+  if (self = [super initWithFrame:frame]) {
+    static const auto defaultProps = std::make_shared<const AudioWaveformViewProps>();
+    _props = defaultProps;
+
+    _impl = [[AudioWaveformViewImpl alloc] init];
+    self.contentView = _impl;
+
+    [self wireImplCallbacks];
+  }
+  return self;
+}
+
+- (void)wireImplCallbacks
+{
+  __weak __typeof__(self) weakSelf = self;
+
+  _impl.onLoad = ^(NSInteger durationMs) {
+    [weakSelf emitOnLoad:durationMs];
+  };
+  _impl.onLoadError = ^(NSString *_Nonnull message) {
+    [weakSelf emitOnLoadError:message];
+  };
+  _impl.onPlayerStateChange =
+      ^(NSString *_Nonnull state, BOOL isPlaying, float speed, NSString *_Nonnull error) {
+        [weakSelf emitOnPlayerStateChange:state
+                                isPlaying:isPlaying
+                                    speed:speed
+                                    error:error];
+      };
+  _impl.onTimeUpdate = ^(NSInteger currentTimeMs, NSInteger durationMs) {
+    [weakSelf emitOnTimeUpdate:currentTimeMs durationMs:durationMs];
+  };
+  _impl.onSeek = ^(NSInteger positionMs) {
+    [weakSelf emitOnSeek:positionMs];
+  };
+  _impl.onEnd = ^{
+    [weakSelf emitOnEnd];
+  };
+}
+
+#pragma mark - Event emitter forwarding
+
+- (std::shared_ptr<const AudioWaveformViewEventEmitter>)typedEventEmitter
+{
+  return std::static_pointer_cast<const AudioWaveformViewEventEmitter>(_eventEmitter);
+}
+
+- (void)emitOnLoad:(NSInteger)durationMs
+{
+  if (auto e = [self typedEventEmitter]) {
+    e->onLoad({.durationMs = static_cast<int>(durationMs)});
+  }
+}
+
+- (void)emitOnLoadError:(NSString *)message
+{
+  if (auto e = [self typedEventEmitter]) {
+    e->onLoadError({.message = std::string([message UTF8String] ?: "")});
+  }
+}
+
+- (void)emitOnPlayerStateChange:(NSString *)state
+                      isPlaying:(BOOL)isPlaying
+                          speed:(float)speed
+                          error:(NSString *)error
+{
+  if (auto e = [self typedEventEmitter]) {
+    AudioWaveformViewEventEmitter::OnPlayerStateChange event = {
+        .state = std::string([state UTF8String] ?: "idle"),
+        .isPlaying = static_cast<bool>(isPlaying),
+        .speed = static_cast<Float>(speed),
+        .error = std::string([error UTF8String] ?: ""),
+    };
+    e->onPlayerStateChange(event);
+  }
+}
+
+- (void)emitOnTimeUpdate:(NSInteger)currentTimeMs durationMs:(NSInteger)durationMs
+{
+  if (auto e = [self typedEventEmitter]) {
+    e->onTimeUpdate({
+        .currentTimeMs = static_cast<int>(currentTimeMs),
+        .durationMs = static_cast<int>(durationMs),
+    });
+  }
+}
+
+- (void)emitOnSeek:(NSInteger)positionMs
+{
+  if (auto e = [self typedEventEmitter]) {
+    e->onSeek({.positionMs = static_cast<int>(positionMs)});
+  }
+}
+
+- (void)emitOnEnd
+{
+  if (auto e = [self typedEventEmitter]) {
+    e->onEnd({});
+  }
+}
+
+#pragma mark - Props
+
+- (void)updateProps:(const Props::Shared &)props oldProps:(const Props::Shared &)oldProps
+{
+  const auto &oldViewProps =
+      *std::static_pointer_cast<AudioWaveformViewProps const>(_props);
+  const auto &newViewProps = *std::static_pointer_cast<AudioWaveformViewProps const>(props);
+
+  // Source URI
+  if (oldViewProps.source.uri != newViewProps.source.uri) {
+    NSString *uri = [NSString stringWithUTF8String:newViewProps.source.uri.c_str()];
+    _impl.sourceURI = uri ?: @"";
+  }
+
+  // Pre-computed samples
+  if (oldViewProps.samples != newViewProps.samples) {
+    if (newViewProps.samples.empty()) {
+      _impl.providedSamples = nil;
+    } else {
+      NSMutableArray<NSNumber *> *arr =
+          [NSMutableArray arrayWithCapacity:newViewProps.samples.size()];
+      for (auto v : newViewProps.samples) {
+        [arr addObject:@(v)];
+      }
+      _impl.providedSamples = arr;
+    }
+  }
+
+  // Bar colors
+  if (oldViewProps.playedBarColor != newViewProps.playedBarColor) {
+    _impl.playedBarColor =
+        RCTUIColorFromSharedColor(newViewProps.playedBarColor) ?: [UIColor whiteColor];
+  }
+  if (oldViewProps.unplayedBarColor != newViewProps.unplayedBarColor) {
+    _impl.unplayedBarColor = RCTUIColorFromSharedColor(newViewProps.unplayedBarColor)
+        ?: [[UIColor whiteColor] colorWithAlphaComponent:0.5];
+  }
+
+  // Bar geometry
+  if (oldViewProps.barWidth != newViewProps.barWidth) {
+    _impl.barWidth = (CGFloat)newViewProps.barWidth;
+  }
+  if (oldViewProps.barGap != newViewProps.barGap) {
+    _impl.barGap = (CGFloat)newViewProps.barGap;
+  }
+  if (oldViewProps.barRadius != newViewProps.barRadius) {
+    _impl.barRadius = (CGFloat)newViewProps.barRadius;
+  }
+  if (oldViewProps.barCount != newViewProps.barCount) {
+    _impl.barCountOverride = (NSInteger)newViewProps.barCount;
+  }
+
+  // Container background
+  if (oldViewProps.containerBackgroundColor != newViewProps.containerBackgroundColor) {
+    _impl.containerBackgroundColor =
+        RCTUIColorFromSharedColor(newViewProps.containerBackgroundColor)
+        ?: [UIColor colorWithRed:0.204 green:0.471 blue:0.965 alpha:1.0];
+  }
+  if (oldViewProps.containerBorderRadius != newViewProps.containerBorderRadius) {
+    _impl.containerBorderRadius = (CGFloat)newViewProps.containerBorderRadius;
+  }
+  if (oldViewProps.showBackground != newViewProps.showBackground) {
+    _impl.showBackground = newViewProps.showBackground;
+  }
+
+  // Play button
+  if (oldViewProps.showPlayButton != newViewProps.showPlayButton) {
+    _impl.showPlayButton = newViewProps.showPlayButton;
+  }
+  if (oldViewProps.playButtonColor != newViewProps.playButtonColor) {
+    _impl.playButtonColor =
+        RCTUIColorFromSharedColor(newViewProps.playButtonColor) ?: [UIColor whiteColor];
+  }
+
+  // Time
+  if (oldViewProps.showTime != newViewProps.showTime) {
+    _impl.showTime = newViewProps.showTime;
+  }
+  if (oldViewProps.timeColor != newViewProps.timeColor) {
+    _impl.timeColor = RCTUIColorFromSharedColor(newViewProps.timeColor) ?: [UIColor whiteColor];
+  }
+  if (oldViewProps.timeMode != newViewProps.timeMode) {
+    NSString *mode = (newViewProps.timeMode == AudioWaveformViewTimeMode::CountDown)
+        ? @"count-down"
+        : @"count-up";
+    _impl.timeMode = mode;
+  }
+
+  // Speed
+  if (oldViewProps.showSpeedControl != newViewProps.showSpeedControl) {
+    _impl.showSpeedControl = newViewProps.showSpeedControl;
+  }
+  if (oldViewProps.speedColor != newViewProps.speedColor) {
+    _impl.speedColor =
+        RCTUIColorFromSharedColor(newViewProps.speedColor) ?: [UIColor whiteColor];
+  }
+  if (oldViewProps.speedBackgroundColor != newViewProps.speedBackgroundColor) {
+    _impl.speedBackgroundColor =
+        RCTUIColorFromSharedColor(newViewProps.speedBackgroundColor)
+        ?: [[UIColor whiteColor] colorWithAlphaComponent:0.25];
+  }
+  if (oldViewProps.speeds != newViewProps.speeds) {
+    NSArray<NSNumber *> *speeds = [self speedsArrayFrom:newViewProps.speeds];
+    _impl.speeds = speeds;
+  }
+  if (oldViewProps.defaultSpeed != newViewProps.defaultSpeed) {
+    _impl.defaultSpeed = newViewProps.defaultSpeed;
+  }
+
+  // Playback config
+  if (oldViewProps.autoPlay != newViewProps.autoPlay) {
+    _impl.autoPlay = newViewProps.autoPlay;
+  }
+  if (oldViewProps.initialPositionMs != newViewProps.initialPositionMs) {
+    _impl.initialPositionMs = newViewProps.initialPositionMs;
+  }
+  if (oldViewProps.loop != newViewProps.loop) {
+    _impl.loop = newViewProps.loop;
+  }
+  if (oldViewProps.playInBackground != newViewProps.playInBackground) {
+    _impl.playInBackground = newViewProps.playInBackground;
+  }
+  if (oldViewProps.pauseUiUpdatesInBackground != newViewProps.pauseUiUpdatesInBackground) {
+    _impl.pauseUiUpdatesInBackground = newViewProps.pauseUiUpdatesInBackground;
+  }
+
+  // Controlled props
+  if (oldViewProps.controlledPlaying != newViewProps.controlledPlaying) {
+    _impl.controlledPlaying = newViewProps.controlledPlaying;
+  }
+  if (oldViewProps.controlledSpeed != newViewProps.controlledSpeed) {
+    _impl.controlledSpeed = newViewProps.controlledSpeed;
+  }
+
+  [super updateProps:props oldProps:oldProps];
+}
+
+- (NSArray<NSNumber *> *)speedsArrayFrom:(const std::vector<Float> &)values
+{
+  if (values.empty()) {
+    return @[ @0.5, @1.0, @1.5, @2.0 ];
+  }
+  NSMutableArray<NSNumber *> *arr = [NSMutableArray arrayWithCapacity:values.size()];
+  for (auto v : values) {
+    [arr addObject:@(v)];
+  }
+  return arr;
+}
+
+#pragma mark - Commands
+
+- (void)handleCommand:(const NSString *)commandName args:(const NSArray *)args
+{
+  if ([commandName isEqualToString:@"play"]) {
+    [_impl play];
+  } else if ([commandName isEqualToString:@"pause"]) {
+    [_impl pause];
+  } else if ([commandName isEqualToString:@"toggle"]) {
+    [_impl toggle];
+  } else if ([commandName isEqualToString:@"seekTo"] && args.count >= 1) {
+    NSInteger ms = [args[0] integerValue];
+    [_impl seekToMs:ms];
+  } else if ([commandName isEqualToString:@"setSpeed"] && args.count >= 1) {
+    float s = [args[0] floatValue];
+    [_impl setSpeedValue:s];
+  }
+}
+
+- (void)prepareForRecycle
+{
+  [super prepareForRecycle];
+  static const auto defaultProps = std::make_shared<const AudioWaveformViewProps>();
+  _props = defaultProps;
+}
+
+@end