#lang scribble/manual

@(require (for-label racket/base
                     racket/contract
                     (file "../main.rkt")
                     (file "../services/av-transport.rkt")))

@title{AVTransport}

@defmodule[@racketmodname[racket-upnp/services/av-transport] #:module-paths ((file "../services/av-transport.rkt"))]

AVTransport controls the playback state of a MediaRenderer. The media itself
is normally fetched by the renderer from the URI supplied by the control
point.

@defproc[(device-av-transport [device upnp-device?]) (or/c #f upnp-service?)]{Returns the device's AVTransport service.}
@defproc[(av-transport? [value any/c]) boolean?]{Recognises an AVTransport service.}
@defproc[(av-transport-set-uri! [transport av-transport?]
                                [uri string?]
                                [#:metadata metadata string? ""]
                                [#:instance-id instance-id exact-nonnegative-integer? 0])
         void?]{Sets the current transport URI and optional DIDL-Lite metadata.}
@defproc[(av-transport-play! [transport av-transport?]
                             [#:speed speed any/c 1]
                             [#:instance-id instance-id exact-nonnegative-integer? 0])
         void?]{Starts playback.}
@defproc[(av-transport-pause! [transport av-transport?]
                              [#:instance-id instance-id exact-nonnegative-integer? 0]) void?]{Pauses playback.}
@defproc[(av-transport-stop! [transport av-transport?]
                             [#:instance-id instance-id exact-nonnegative-integer? 0]) void?]{Stops playback.}
@defproc[(av-transport-seek! [transport av-transport?]
                             [seconds nonnegative-real?]
                             [#:instance-id instance-id exact-nonnegative-integer? 0]) void?]{Seeks using the UPnP @tt{REL_TIME} unit.}
@defproc[(av-transport-status [transport av-transport?]
                              [#:instance-id instance-id exact-nonnegative-integer? 0]) symbol?]{Returns a state such as @racket['playing], @racket['paused], @racket['stopped], or @racket['unknown].}
@defproc[(av-transport-position [transport av-transport?]
                                [#:instance-id instance-id exact-nonnegative-integer? 0]) transport-position?]{Returns the current track, position, duration, and URI.}

@section{Position values}

@defproc[(transport-position? [value any/c]) boolean?]{Recognises an AVTransport position value.}
@defproc[(transport-position-track [position transport-position?]) (or/c #f exact-integer?)]{Returns the current track number.}
@defproc[(transport-position-seconds [position transport-position?]) (or/c #f nonnegative-real?)]{Returns the current relative position in seconds.}
@defproc[(transport-position-duration [position transport-position?]) (or/c #f nonnegative-real?)]{Returns the track duration in seconds.}
@defproc[(transport-position-uri [position transport-position?]) (or/c #f string?)]{Returns the current track URI.}