added subtitles support

Author: swiftuiux

README.md

@@ -62,7 +62,7 @@ Please note that using videos from URLs requires ensuring that you have the righ
 |---------------|-----------------------------------------------------------------------------------------------------|---------|
 | **SourceName** | The URL or local filename of the video.                                                             | -       |
 | **Ext**        | File extension for the video, used when loading from local resources. This is optional when a URL is provided and the URL ends with the video file extension. | "mp4"  |
-| **Subtitles**  | The URL or local filename of the WebVTT (.vtt) subtitles file to be merged with the video. With a straightforward AVMutableComposition approach, you cannot directly change the position or size of subtitles. AVFoundation’s built-in handling of “text” tracks simply renders them in a default style, without allowing additional layout options.         | -       |
+| **Subtitles**  | The URL or local filename of the WebVTT (.vtt) subtitles file to be merged with the video. With a straightforward AVMutableComposition approach, you cannot directly change the position or size of subtitles. AVFoundation’s built-in handling of “text” tracks simply renders them in a default style, without allowing additional layout options. Take a look the implementation in the example app (Video8.swift)  | -       |
 | **Gravity** | How the video content should be resized to fit the player's bounds. | .resizeAspect |
 | **TimePublishing** | Specifies the interval at which the player publishes the current playback time. | - |
 | **Loop** | Whether the video should automatically restart when it reaches the end. If not explicitly passed, the video will not loop. | false |

Sources/swiftui-loop-videoplayer/enum/Setting.swift

@@ -36,6 +36,9 @@ public enum Setting: Equatable, SettingsConvertible{
     /// File extension
     case ext(String)
 
+    /// Subtitles
+    case subtitles(String)
+    
     /// A CMTime value representing the interval at which the player's current time should be published.
     /// If set, the player will publish periodic time updates based on this interval.
     case timePublishing(CMTime)

Sources/swiftui-loop-videoplayer/fn/fn+.swift

@@ -106,3 +106,102 @@ internal func handleVideoComposition(request: AVAsynchronousCIImageFilteringRequ
     request.finish(with: currentImage, context: nil)
 }
 
+/// Retrieves an `AVURLAsset` for the subtitles specified in `VideoSettings`.
+/// - Parameter settings: The `VideoSettings` object containing details about the subtitle file (e.g., name and extension).
+/// - Returns: An optional `AVURLAsset` for the subtitle file, or `nil` if the file does not exist.
+func subtitlesFor(_ settings: VideoSettings) -> AVURLAsset? {
+    let name = settings.subtitles
+    let ext = "vtt"
+    
+    if name.isEmpty { return nil }
+    
+    // Attempt to create a URL directly from the provided video name string
+    if let url = URL.validURLFromString(name) {
+        return AVURLAsset(url: url)
+    // If direct URL creation fails, attempt to locate the video in the main bundle using the name and extension
+    } else if let fileUrl = Bundle.main.url(forResource: name, withExtension: ext) {
+        return AVURLAsset(url: fileUrl)
+    }
+    
+    return nil
+}
+
+/// Merges a video asset with an external WebVTT subtitle file into an AVMutableComposition.
+/// Returns a new AVAsset that has both the video/audio and subtitle tracks.
+///
+/// - Note:
+///   - This method supports embedding external subtitles (e.g., WebVTT) into video files
+///     that can handle text tracks, such as MP4 or QuickTime (.mov).
+///   - Subtitles are added as a separate track within the composition and will not be rendered
+///     (burned-in) directly onto the video frames. Styling, position, and size cannot be customized.
+///
+/// - Parameters:
+///   - videoAsset: The video asset (e.g., an MP4 file) to which the subtitles will be added.
+///   - subtitleAsset: The WebVTT subtitle asset to be merged with the video.
+///
+/// - Returns: A new AVAsset with the video, audio, and subtitle tracks combined.
+///            Returns `nil` if an error occurs during the merging process or if subtitles are unavailable.
+func mergeAssetWithSubtitles(videoAsset: AVURLAsset, subtitleAsset: AVURLAsset) -> AVAsset?  {
+    // Create a new composition
+    let composition = AVMutableComposition()
+
+    // 1) Copy the VIDEO track (and AUDIO track if available) from the original video
+    do {
+        // VIDEO
+        if let videoTrack = videoAsset.tracks(withMediaType: .video).first {
+            let compVideoTrack = composition.addMutableTrack(
+                withMediaType: .video,
+                preferredTrackID: kCMPersistentTrackID_Invalid
+            )
+            try compVideoTrack?.insertTimeRange(
+                CMTimeRange(start: .zero, duration: videoAsset.duration),
+                of: videoTrack,
+                at: .zero
+            )
+        }
+        // AUDIO (if your video has an audio track)
+        if let audioTrack = videoAsset.tracks(withMediaType: .audio).first {
+            let compAudioTrack = composition.addMutableTrack(
+                withMediaType: .audio,
+                preferredTrackID: kCMPersistentTrackID_Invalid
+            )
+            try compAudioTrack?.insertTimeRange(
+                CMTimeRange(start: .zero, duration: videoAsset.duration),
+                of: audioTrack,
+                at: .zero
+            )
+        }
+    } catch {
+        #if DEBUG
+        print("Error adding video/audio tracks: \(error)")
+        #endif
+        return nil
+    }
+    
+    // 2) Find the TEXT track in the subtitle asset
+    guard let textTrack = subtitleAsset.tracks(withMediaType: .text).first else {
+        #if DEBUG
+        print("No text track found in subtitle file.")
+        #endif
+        return composition // Return just the video/audio if no text track
+    }
+    
+    // 3) Insert the subtitle track into the composition
+    do {
+        let compTextTrack = composition.addMutableTrack(
+            withMediaType: .text,
+            preferredTrackID: kCMPersistentTrackID_Invalid
+        )
+        try compTextTrack?.insertTimeRange(
+            CMTimeRange(start: .zero, duration: videoAsset.duration),
+            of: textTrack,
+            at: .zero
+        )
+    } catch {
+        #if DEBUG
+        print("Error adding text track: \(error)")
+        #endif
+    }
+
+    return composition
+}

Sources/swiftui-loop-videoplayer/protocol/player/LoopingPlayerProtocol.swift

@@ -37,8 +37,6 @@ public protocol LoopingPlayerProtocol: AbstractPlayer, LayerMakerProtocol{
     /// ensuring that all playback errors are managed and reported appropriately.
     var errorObserver: NSKeyValueObservation? { get set }
 
-
-    
     /// An optional observer for monitoring changes to the player's `timeControlStatus` property.
     var timeControlObserver: NSKeyValueObservation? { get set }
 
@@ -139,7 +137,8 @@ internal extension LoopingPlayerProtocol {
         for item in items {
             player?.remove(item)
         }
-    }
+    }    
+
 
     /// Updates the current playback asset, settings, and initializes playback or a specific action when the asset is ready.
     ///
@@ -150,12 +149,14 @@ internal extension LoopingPlayerProtocol {
     ///   - asset: The AVURLAsset to be loaded into the player.
     ///   - settings: The `VideoSettings` struct that includes all necessary configurations like gravity, loop, and mute.
     ///   - callback: An optional closure to be called when the asset is ready to play.
-    func update(asset: AVURLAsset,  settings: VideoSettings, callback: ((AVPlayerItem.Status) -> Void)? = nil) {
-
+    func update(
+        asset: AVURLAsset,
+        settings: VideoSettings,
+        callback: ((AVPlayerItem.Status) -> Void)? = nil
+    ) {
         guard let player = player else { return }
 
         currentSettings = settings
-        
         player.pause()
 
         if !player.items().isEmpty {
@@ -165,17 +166,31 @@ internal extension LoopingPlayerProtocol {
             removeAllFilters()
         }
 
-        let newItem = AVPlayerItem(asset: asset)
+        let newItem: AVPlayerItem
+        
+        // try to retrieve the .vtt subtitle
+        if let subtitleAsset = subtitlesFor(settings),
+           let mergedAsset = mergeAssetWithSubtitles(videoAsset: asset, subtitleAsset: subtitleAsset) {
+            // Create a new AVPlayerItem from the merged asset
+            newItem = AVPlayerItem(asset: mergedAsset)
+        }else{
+            // Create a new AVPlayerItem from the merged asset
+            newItem = AVPlayerItem(asset: asset)
+        }
+
+        // Insert the new item into the player queue
         player.insert(newItem, after: nil)
 
+        // Loop if required
         if settings.loop {
             loop()
         }
 
-        // Set up state item status observer
+        // Observe status changes
         setupStateItemStatusObserver(newItem: newItem, callback: callback)
-      
-        if !settings.notAutoPlay{
+
+        // Autoplay if allowed
+        if !settings.notAutoPlay {
             play()
         }
     }

Sources/swiftui-loop-videoplayer/settings/Subtitles.swift

@@ -0,0 +1,34 @@
+//
+//  Subtitles.swift
+//  swiftui-loop-videoplayer
+//
+//  Created by Igor Shelopaev on 07.01.25.
+//
+
+/// Represents a structure that holds the name of subtitles, conforming to `SettingsConvertible`.
+///
+/// Important:
+/// - When using `.vtt` subtitles, a file-based container format such as MP4 or QuickTime (`.mov`)
+///   generally supports embedding those subtitles as a `.text` track.
+/// - Formats like HLS (`.m3u8`) typically reference `.vtt` files externally rather than merging them
+///   into a single file.
+/// - Attempting to merge `.vtt` subtitles into an HLS playlist via `AVMutableComposition` won't work;
+///   instead, you’d attach the `.vtt` as a separate media playlist in the HLS master manifest.
+@available(iOS 14.0, macOS 11.0, tvOS 14.0, *)
+public struct Subtitles : SettingsConvertible{
+          
+    /// Video file name
+    let value : String
+    
+    // MARK: - Life circle
+    
+    /// Initializes a new instance with a specific video file name.
+    /// - Parameter value: The string representing the video file name.
+    public init(_ value: String) { self.value = value }
+    
+    /// Fetch settings
+    @_spi(Private)
+    public func asSettings() -> [Setting] {
+        [.subtitles(value)]
+    }
+}

Sources/swiftui-loop-videoplayer/utils/VideoSettings.swift

@@ -20,6 +20,9 @@ public struct VideoSettings: Equatable{
     /// Video extension
     public let ext: String
 
+    /// Subtitles
+    public let subtitles: String
+    
     /// Loop video
     public let loop: Bool
 
@@ -69,9 +72,10 @@ public struct VideoSettings: Equatable{
     ///   - errorColor: The color used for error messages.
     ///   - errorFontSize: The font size for error messages.
     ///   - errorWidgetOff: A Boolean indicating whether the error widget should be turned off.
-    public init(name: String, ext: String, loop: Bool, mute: Bool, notAutoPlay: Bool, timePublishing: CMTime?, gravity: AVLayerVideoGravity, errorColor: Color, errorFontSize: CGFloat, errorWidgetOff: Bool) {
+    public init(name: String, ext: String, subtitles: String, loop: Bool, mute: Bool, notAutoPlay: Bool, timePublishing: CMTime?, gravity: AVLayerVideoGravity, errorColor: Color, errorFontSize: CGFloat, errorWidgetOff: Bool) {
         self.name = name
         self.ext = ext
+        self.subtitles = subtitles
         self.loop = loop
         self.mute = mute
         self.notAutoPlay = notAutoPlay
@@ -94,6 +98,8 @@ public struct VideoSettings: Equatable{
 
         ext = settings.fetch(by : "ext", defaulted: "mp4")
 
+        subtitles = settings.fetch(by : "subtitles", defaulted: "")
+        
         gravity = settings.fetch(by : "gravity", defaulted: .resizeAspect)
 
         errorColor = settings.fetch(by : "errorColor", defaulted: .red)
@@ -117,21 +123,21 @@ public extension VideoSettings {
 
     /// Returns a new instance of VideoSettings with loop set to false and notAutoPlay set to true, keeping other settings unchanged.
     var GetSettingsWithNotAutoPlay : VideoSettings {
-        VideoSettings(name: self.name, ext: self.ext, loop: self.loop, mute: self.mute, notAutoPlay: true, timePublishing: self.timePublishing, gravity: self.gravity, errorColor: self.errorColor, errorFontSize: self.errorFontSize, errorWidgetOff: self.errorWidgetOff)
+        VideoSettings(name: self.name, ext: self.ext, subtitles: self.subtitles, loop: self.loop, mute: self.mute, notAutoPlay: true, timePublishing: self.timePublishing, gravity: self.gravity, errorColor: self.errorColor, errorFontSize: self.errorFontSize, errorWidgetOff: self.errorWidgetOff)
     }
 
     /// Checks if the asset has changed based on the provided settings and current asset.
     /// - Parameters:
     ///   - asset: The current asset being played.
     /// - Returns: A new `AVURLAsset` if the asset has changed, or `nil` if the asset remains the same.
-    func getAssetIfDifferent(than asset: AVURLAsset?) -> AVURLAsset?{
+    func getAssetIfDifferent(_ settings : VideoSettings?) -> AVURLAsset?{
         let newAsset =  assetFor(self)
 
-        if asset == nil {
-            return newAsset
-        }
+        guard let settings = settings else{ return newAsset }
+        
+        let oldAsset = assetFor(settings)
 
-        if let newUrl = newAsset?.url, let oldUrl = asset?.url, newUrl != oldUrl{
+        if let newUrl = newAsset?.url, let oldUrl = oldAsset?.url, newUrl != oldUrl{
             return newAsset
         }
 

Sources/swiftui-loop-videoplayer/view/main/LoopPlayerMultiPlatform.swift

@@ -114,8 +114,9 @@ extension LoopPlayerMultiPlatform: UIViewRepresentable{
     ///   - context: The context for the view
     @MainActor func updateUIView(_ uiView: UIView, context: Context) {
         let player = uiView.findFirstSubview(ofType: PlayerView.self)
-        if let player {
-            if let asset = settings.getAssetIfDifferent(than: player.currentAsset) {
+       
+        if let player{
+            if let asset = settings.getAssetIfDifferent(player.currentSettings) {
                 player.update(asset: asset, settings: settings)
             }
 
@@ -163,7 +164,7 @@ extension LoopPlayerMultiPlatform: NSViewRepresentable{
     @MainActor func updateNSView(_ nsView: NSView, context: Context) {
         let player = nsView.findFirstSubview(ofType: PlayerView.self)
         if let player {
-            if let asset = settings.getAssetIfDifferent(than: player.currentAsset){
+            if let asset = settings.getAssetIfDifferent(player.currentSettings){
                 player.update(asset: asset, settings: settings)
             }
             // Check if command changed before applying it