add support for "already watched" time value on YTVideo

Author: b5i

Sources/YouTubeKit/BaseStructs/YTVideo+timeStringToSeconds.swift

@@ -0,0 +1,25 @@
+//
+//  YTVideo+timeStringToSeconds.swift
+//  YouTubeKit
+//
+//  Created by Antoine Bollengier on 02.01.2026.
+//  Copyright © 2026 Antoine Bollengier (github.com/b5i). All rights reserved.
+//  
+
+import Foundation
+
+public extension YTVideo {
+    /// Converts a time string (e.g. "1:30") to seconds.
+    /// - Parameter timeString: The time string to convert.
+    /// - Returns: The time in seconds, or nil if the format is invalid.
+    static func timeStringToSeconds(_ timeString: String) -> Int? {
+        let components = timeString.split(separator: ":").map(String.init)
+        guard components.count <= 2 else { return nil }
+        
+        let seconds = components.reversed().enumerated().reduce(0) { (total, element) in
+            guard let value = Int(element.element) else { return total }
+            return total + value * Int(pow(60, Double(element.offset)))
+        }
+        return seconds
+    }
+}

Sources/YouTubeKit/BaseStructs/YTVideo.swift

@@ -9,7 +9,7 @@ import Foundation
 
 /// Struct representing a video.
 public struct YTVideo: YTSearchResult, YouTubeVideo, Codable, Sendable {
-    public init(id: Int? = nil, videoId: String, title: String? = nil, channel: YTLittleChannelInfos? = nil, viewCount: String? = nil, timePosted: String? = nil, timeLength: String? = nil, thumbnails: [YTThumbnail] = [], memberOnly: Bool? = nil) {
+    public init(id: Int? = nil, videoId: String, title: String? = nil, channel: YTLittleChannelInfos? = nil, viewCount: String? = nil, timePosted: String? = nil, timeLength: String? = nil, thumbnails: [YTThumbnail] = [], memberOnly: Bool? = nil, startTime: Int? = nil) {
         self.id = id
         self.videoId = videoId
         self.title = title
@@ -19,10 +19,11 @@ public struct YTVideo: YTSearchResult, YouTubeVideo, Codable, Sendable {
         self.timeLength = timeLength
         self.thumbnails = thumbnails
         self.memberOnly = memberOnly
+        self.startTime = startTime
     }
 
     public static func == (lhs: YTVideo, rhs: YTVideo) -> Bool {
-        return lhs.channel?.channelId == rhs.channel?.channelId && lhs.channel?.name == rhs.channel?.name && lhs.thumbnails == rhs.thumbnails && lhs.timeLength == rhs.timeLength && lhs.timePosted == rhs.timePosted && lhs.title == rhs.title && lhs.videoId == rhs.videoId && lhs.viewCount == rhs.viewCount && lhs.memberOnly == rhs.memberOnly
+        return lhs.channel?.channelId == rhs.channel?.channelId && lhs.channel?.name == rhs.channel?.name && lhs.thumbnails == rhs.thumbnails && lhs.timeLength == rhs.timeLength && lhs.timePosted == rhs.timePosted && lhs.title == rhs.title && lhs.videoId == rhs.videoId && lhs.viewCount == rhs.viewCount && lhs.memberOnly == rhs.memberOnly && lhs.startTime == rhs.startTime
     }
 
     public static func canBeDecoded(json: JSON) -> Bool {
@@ -87,6 +88,8 @@ public struct YTVideo: YTSearchResult, YouTubeVideo, Codable, Sendable {
 
         YTThumbnail.appendThumbnails(json: json["thumbnail"], thumbnailList: &video.thumbnails)
 
+        video.startTime = Int(Double(json["thumbnailOverlays", 0, "thumbnailOverlayResumePlaybackRenderer", "percentDurationWatched"].intValue) * 0.01 * Double(video.timeLengthSeconds ?? 0).rounded(.down))
+        
         return video
     }
 
@@ -123,7 +126,9 @@ public struct YTVideo: YTSearchResult, YouTubeVideo, Codable, Sendable {
 
         YTThumbnail.appendThumbnails(json: json["contentImage", "thumbnailViewModel"], thumbnailList: &video.thumbnails)
 
-        video.timeLength = json["contentImage", "thumbnailViewModel", "overlays"].array?.first?["thumbnailOverlayBadgeViewModel", "thumbnailBadges"].array?.first?["thumbnailBadgeViewModel", "text"].string
+        video.timeLength = json["contentImage", "thumbnailViewModel", "overlays", 0, "thumbnailOverlayBadgeViewModel", "thumbnailBadges", 0, "thumbnailBadgeViewModel", "text"].string ?? json["contentImage", "thumbnailViewModel", "overlays", 0, "thumbnailBottomOverlayViewModel", "badges", 0, "thumbnailBadgeViewModel", "text"].string
+        
+        video.startTime = json["rendererContext", "commandContext", "onTap", "innertubeCommand", "watchEndpoint", "startTimeSeconds"].int
 
         return video
     }
@@ -146,6 +151,9 @@ public struct YTVideo: YTSearchResult, YouTubeVideo, Codable, Sendable {
     /// A boolean inidicating whether the video is a member-only one. If it's true, you won't be able to request the streaming info of the video except if you provide the cookies of an account that's a member of the channel.
     public var memberOnly: Bool?
 
+    /// The start time of the video in seconds, represents the time that was already partially watched.
+    public var startTime: Int?
+    
     /// Count of views of the video, in a shortened string.
     ///
     /// Possibly not defined when reading in ``YTPlaylist/frontVideos`` properties.
@@ -163,6 +171,14 @@ public struct YTVideo: YTSearchResult, YouTubeVideo, Codable, Sendable {
     /// Can be `live` instead of `ab:cd` if the video is a livestream.
     public var timeLength: String?
 
+    /// Length in seconds of the video, extracted from ``timeLength``.
+    public var timeLengthSeconds: Int? {
+        if let timeLength {
+            return Self.timeStringToSeconds(timeLength)
+        }
+        return nil
+    }
+    
     /// Array of thumbnails.
     ///
     /// Usually sorted by resolution, from low to high.

Sources/YouTubeKit/YouTubeResponseTypes/VideoInfos/VideoInfosResponse.swift

@@ -89,6 +89,11 @@ public struct VideoInfosResponse: YouTubeResponse {
     /// The aspect ratio of the video (width/height).
     public var aspectRatio: Double?
 
+    /// The start time of the video in seconds, represents the time that was already partially watched or that the "t" parameter is set in the video URL. Currently disabled because we can't make VideoInfosResponse requests with cookies.
+    ///
+    /// - Note: This property is also available on ``YTVideo/startTime``, please use this value.
+    //public var startTime: Int? = nil
+    
     /// Array of formats used to download the video, they usually contain both audio and video data and the download speed is higher than the ``VideoInfosResponse/downloadFormats``.
     //@available(*, deprecated, message: "This property is unstable for the moment.")
     public var defaultFormats: [any DownloadFormat]
@@ -110,6 +115,7 @@ public struct VideoInfosResponse: YouTubeResponse {
         videoURLsExpireAt: Date? = nil,
         viewCount: String? = nil,
         aspectRatio: Double? = nil,
+        //startTime: Int? = nil,
         defaultFormats: [any DownloadFormat] = [],
         downloadFormats: [any DownloadFormat] = []
     ) {
@@ -125,6 +131,7 @@ public struct VideoInfosResponse: YouTubeResponse {
         self.videoURLsExpireAt = videoURLsExpireAt
         self.viewCount = viewCount
         self.aspectRatio = aspectRatio
+        //self.startTime = startTime
         self.defaultFormats = defaultFormats
         self.downloadFormats = downloadFormats
     }
@@ -188,6 +195,7 @@ public struct VideoInfosResponse: YouTubeResponse {
             }(),
             viewCount: videoDetailsJSON["viewCount"].string,
             aspectRatio: streamingJSON["aspectRatio"].double,
+            //startTime: json["playerConfig", "playbackStartConfig", "startSeconds"].int,
             defaultFormats: streamingJSON["formats"].arrayValue.compactMap { VideoInfosWithDownloadFormatsResponse.decodeFormatFromJSON(json: $0) },
             downloadFormats: streamingJSON["adaptiveFormats"].arrayValue.compactMap { VideoInfosWithDownloadFormatsResponse.decodeFormatFromJSON(json: $0) }
         )