Playback

Play scanned local files, streams.

Seanime provides APIs for controlling media playback and interacting with the underlying Playback Manager and MPV. These APIs give plugins access to the same functionality Seanime uses internally for media tracking and player control.

Permissions

playback permission is required

{
  //...
  "plugin": {
    "permissions": {
      "scopes": ["playback"]
    }
  }
}

Core methods

playUsingMediaPlayer

playUsingMediaPlayer(filePath)

Plays a local file using the configured media player, with automatic tracking.

Parameters:

• filePath: String - Path to a scanned local video file

Returns: Promise<void>

Note: This only works with files properly scanned by Seanime. Using it with unscanned files will result in tracking errors.

Example:

// Play a local file with tracking
try {
  await ctx.playback.playUsingMediaPlayer("/anime/One Piece/One Piece - 1015.mkv")
  console.log("Playback started successfully")
} catch (error) {
  console.error("Playback error:", error)
}

streamUsingMediaPlayer

streamUsingMediaPlayer(windowTitle, streamUrl, anime, aniDbEpisode)

Streams a video from a URL using the configured media player, with automatic tracking.

Parameters:

• windowTitle: String - Title for the player window

• streamUrl: String - URL of the video stream

• anime: AL_BaseAnime - AniList anime object

• aniDbEpisode: String - AniDB episode number

Returns: Promise<void>

Example:

// Stream an episode with proper tracking
const anime = $anilist.getAnime(21) // One Piece
try {
  await ctx.playback.streamUsingMediaPlayer(
    "One Piece - Episode 1015", 
    "https://example.com/streams/one-piece-1015.mkv",
    anime,
    "1015"
  )
  console.log("Stream started successfully")
} catch (error) {
  console.error("Stream error:", error)
}

registerEventListener

registerEventListener(id, callback)

Registers a listener for playback events.

Parameters:

• id: String - Unique identifier for the listener

• callback: Function(event: PlaybackEvent) - Function called when an event occurs

Returns: Function - Call this function to unregister the listener

Example:

// Listen for playback events
const unsubscribe = ctx.playback.registerEventListener((event) => {
  if (event.isVideoStarted) {
    console.log(`Started playback of: ${event.startedEvent.filename}`)
  } else if (event.status) {
    const progress = event.status.completionPercentage
    console.log(`Playback progress: ${Math.round(progress)}%`)
  } else if (event.isVideoCompleted) {
    console.log(`Completed playback of: ${event.completedEvent.filename}`)
  }
})

// Later, to stop listening
unsubscribe()

pause()

Pauses the current playback.

Example:

try {
  ctx.playback.pause()
  console.log("Playback paused")
} catch (error) {
  console.error("Could not pause:", error)
}

resume()

Resumes the paused playback.

Example:

// Resume after pausing
try {
  ctx.playback.resume()
  console.log("Playback resumed")
} catch (error) {
  console.error("Could not resume:", error)
}

seek(seconds)

Seeks to a specific position in the current playback.

Parameters:

• seconds: Number - The position to seek to in seconds

Example:

// Skip ahead 30 seconds
try {
  ctx.playback.seek(currentTimeInSeconds + 30)
  console.log("Skipped forward 30 seconds")
} catch (error) {
  console.error("Could not seek:", error)
}

cancel()

Cancels the current playback tracking (does not stop the player).

Example:

// Cancel tracking without stopping playback
try {
  ctx.playback.cancel()
  console.log("Tracking canceled")
} catch (error) {
  console.error("Could not cancel tracking:", error)
}

getNextEpisode()

Gets the next episode to play for the current media.

Returns: Promise<Anime_LocalFile | undefined>

Example:

// Check if there's a next episode
try {
  const nextEpisode = await ctx.playback.getNextEpisode()
  if (nextEpisode) {
    console.log(`Next episode: ${nextEpisode.name}`)
  } else {
    console.log("No next episode available")
  }
} catch (error) {
  console.error("Error getting next episode:", error)
}

playNextEpisode()

Plays the next episode for the current media.

Returns: Promise<void>

Example:

// Play next episode when current is almost done
ctx.playback.registerEventListener((event) => {
  if (event.status && event.status.completionPercentage > 95) {
    try {
      ctx.playback.playNextEpisode()
    } catch(e) {}
  }
})

MPV

openAndPlay(filePath)

Opens and plays a file directly with MPV (without tracking).

Parameters:

• filePath: String - Path to a video file

Returns: Promise<void>

Example:

// Play a file directly with MPV without tracking
try {
  await ctx.mpv.openAndPlay("/path/to/video.mkv")
  console.log("MPV playback started")
} catch (error) {
  console.error("MPV playback error:", error)
}

onEvent(callback)

Registers a listener for MPV player events (fires frequently).

Parameters:

• callback: Function(event, closed) - Callback function for events

Returns: Function - Call this function to unregister the listener

Example:

// Monitor MPV events (use carefully - fires multiple times per second)
const unsubscribe = ctx.mpv.onEvent((event, closed) => {
  if (closed) {
    console.log("MPV connection closed")
    return
  }
  
  console.log("MPV loaded file:", event.data)
})

getConnection()

Returns the connection object to the MPV instance.

Returns: MpvConnection | undefined - The MPV connection if available

stop()

Stops the MPV player.

Returns: Promise<void>

Example:

// Stop playback after 5 minutes
ctx.setTimeout(() => {
  ctx.mpv.stop()
    .then(() => console.log("MPV stopped"))
    .catch(err => console.error("Failed to stop MPV:", err))
}, 5 * 60 * 1000)

MpvConnection

Connection to control MPV directly:

interface MpvConnection {
  call(...args: any[]): void
  set(property: string, value: any): void
  get(property: string): any
  close(): void
  isClosed(): boolean
}

Best Practices

Media Tracking

The playback API is designed for tracked media files that are part of the Seanime library:

// Good practice: Play scanned files for proper tracking
const localFile = getScannedFile() // Get a file that's in the library
ctx.playback.playUsingMediaPlayer(localFile.path)

// Bad practice: Playing unscanned files won't track properly
ctx.playback.playUsingMediaPlayer("/random/video.mp4") // Will cause tracking errors

MPV Connection Management

Handle MPV connections carefully:

// Good practice: Check connection before using
function skipIntro() {
  const conn = ctx.mpv.getConnection()
  if (conn && !conn.isClosed()) {
    const currentTime = conn.get("time-pos") || 0
    conn.set("time-pos", currentTime + 90) // Skip 90 seconds
  }
}

// Bad practice: Not checking connection state
function badSkipFunction() {
  const conn = ctx.mpv.getConnection()
  conn.set("time-pos", 90) // Might fail if connection doesn't exist
}