Sync: add playback methods that accept start/end and pagination #161

Author: UweTrottmann

CHANGELOG.md

@@ -6,6 +6,8 @@
   and `Users.collectionShows()` with required `page` and `limit` parameters. The original methods without pagination 
   parameters are deprecated.
 * Add history endpoints to `Sync`. Thanks @defhead! [#125](https://github.com/UweTrottmann/trakt-java/pull/125)
+* Add `Sync.playback()` that also accepts start and end times and supports pagination. The existing `getPlayback()`
+  methods are deprecated.
 
 ## 6.16.0 - 2024-11-07
 

src/main/java/com/uwetrottmann/trakt5/enums/PlaybackType.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright © 2026 Uwe Trottmann <uwe@uwetrottmann.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.uwetrottmann.trakt5.enums;
+
+public enum PlaybackType implements TraktEnum {
+
+    MOVIES("movies"),
+    EPISODES("episodes");
+
+    private final String value;
+
+    PlaybackType(String value) {
+        this.value = value;
+    }
+
+    @Override
+    public String toString() {
+        return value;
+    }
+
+}

src/main/java/com/uwetrottmann/trakt5/services/Sync.java

@@ -32,6 +32,7 @@
 import com.uwetrottmann.trakt5.entities.WatchlistedSeason;
 import com.uwetrottmann.trakt5.enums.Extended;
 import com.uwetrottmann.trakt5.enums.HistoryType;
+import com.uwetrottmann.trakt5.enums.PlaybackType;
 import com.uwetrottmann.trakt5.enums.RatingsFilter;
 import org.threeten.bp.OffsetDateTime;
 import retrofit2.Call;
@@ -150,11 +151,62 @@ Call<List<BaseMovie>> watchedMovies(
             @Query(value = "extended", encoded = true) Extended extended
     );
 
+    /**
+     * <b>OAuth Required</b>
+     * <p>
+     * Whenever a scrobble is paused, the playback progress is saved. Use this progress to sync up playback across
+     * different media centers or apps. For example, you can start watching a movie in a media center, stop it, then
+     * resume on your tablet from the same spot. Each item will have the progress percentage between 0 and 100.
+     * <p>
+     * Use {@link #playback(PlaybackType, OffsetDateTime, OffsetDateTime, Integer, Integer)} to specify a type to only
+     * get movies or episodes.
+     * <p>
+     * By default, all results will be returned. Pagination is optional and can be used for something like an "on deck"
+     * feature, or if you only need a limited data set.
+     * <p>
+     * Note: Trakt only saves playback progress for the last 6 months.
+     *
+     * @see #playback(PlaybackType, OffsetDateTime, OffsetDateTime, Integer, Integer)
+     */
+    @GET("sync/playback")
+    Call<List<PlaybackResponse>> playback(
+            @Query("start_at") OffsetDateTime startAt,
+            @Query("end_at") OffsetDateTime endAt,
+            @Query("page") Integer page,
+            @Query("limit") Integer limit
+    );
+
+    /**
+     * <b>OAuth Required</b>
+     * <p>
+     * Whenever a scrobble is paused, the playback progress is saved. Use this progress to sync up playback across
+     * different media centers or apps. For example, you can start watching a movie in a media center, stop it, then
+     * resume on your tablet from the same spot. Each item will have the progress percentage between 0 and 100.
+     * <p>
+     * By default, all results will be returned. Pagination is optional and can be used for something like an "on deck"
+     * feature, or if you only need a limited data set.
+     * <p>
+     * Note: Trakt only saves playback progress for the last 6 months.
+     *
+     * @see #playback(OffsetDateTime, OffsetDateTime, Integer, Integer)
+     */
+    @GET("sync/playback/{type}")
+    Call<List<PlaybackResponse>> playback(
+            @Path("type") PlaybackType type,
+            @Query("start_at") OffsetDateTime startAt,
+            @Query("end_at") OffsetDateTime endAt,
+            @Query("page") Integer page,
+            @Query("limit") Integer limit
+    );
+
     /**
      * <b>OAuth Required</b>
      *
      * <p> Returns all playbacks;
+     *
+     * @deprecated Use {@link #playback(OffsetDateTime, OffsetDateTime, Integer, Integer)} instead.
      */
+    @Deprecated
     @GET("sync/playback")
     Call<List<PlaybackResponse>> getPlayback(
             @Query("limit") Integer limit
@@ -164,7 +216,10 @@ Call<List<PlaybackResponse>> getPlayback(
      * <b>OAuth Required</b>
      *
      * <p> Returns all playbacks;
+     *
+     * @deprecated Use {@link #playback(PlaybackType, OffsetDateTime, OffsetDateTime, Integer, Integer)} instead.
      */
+    @Deprecated
     @GET("sync/playback/episodes")
     Call<List<PlaybackResponse>> getPlaybackEpisodes(
             @Query("limit") Integer limit
@@ -174,7 +229,10 @@ Call<List<PlaybackResponse>> getPlaybackEpisodes(
      * <b>OAuth Required</b>
      *
      * <p> Returns all playbacks;
+     *
+     * @deprecated Use {@link #playback(PlaybackType, OffsetDateTime, OffsetDateTime, Integer, Integer)} instead.
      */
+    @Deprecated
     @GET("sync/playback/movies")
     Call<List<PlaybackResponse>> getPlaybackMovies(
             @Query("limit") Integer limit

src/test/java/com/uwetrottmann/trakt5/services/SyncTest.java

@@ -106,7 +106,7 @@ public void test_getPlayback() throws IOException, InterruptedException {
         // Give the server some time to process the request.
         Thread.sleep(1500);
 
-        List<PlaybackResponse> playbacks = executeCall(getTrakt().sync().getPlayback(10));
+        List<PlaybackResponse> playbacks = executeCall(getTrakt().sync().playback(null, null, null, 10));
         assertThat(playbacks).isNotNull();
         boolean foundEpisode = false;
         boolean foundMovie = false;