#lang scribble/manual

@(require
  (for-label
   racket/base
   (file "../media-renderer.rkt")))

@title{Media Renderers}

@defmodule[(file "../media-renderer.rkt")]

This module provides a device-oriented interface for UPnP and DLNA media
renderers.  It hides the AVTransport and RenderingControl services used for
common playback and volume operations.

@defproc[(query-media-renderers
          [#:interface interface (or/c #f string?) #f]
          [#:dns? dns? boolean? #f]
          [#:dlna-only? dlna-only? boolean? #f])
         (listof media-renderer?)]{

Discovers media renderers.  When @racket[dlna-only?] is true, only devices that
advertise a DLNA document identifier are returned.
}

@defproc[(get-media-renderer [filter-name string?])
         (or/c #f media-renderer?)]{

Returns the first discovered renderer whose name contains
@racket[filter-name], ignoring case, or @racket[#f] when no renderer matches.
}

@defproc[(media-renderer? [value any/c]) boolean?]
@defproc[(media-renderer-name [renderer media-renderer?]) string?]
@defproc[(media-renderer-address [renderer media-renderer?]) string?]
@defproc[(media-renderer-manufacturer [renderer media-renderer?])
         (or/c #f string?)]
@defproc[(media-renderer-model [renderer media-renderer?])
         (or/c #f string?)]
@defproc[(media-renderer-dlna? [renderer media-renderer?]) boolean?]

@section{Playback}

@defproc[(media-renderer-play-uri!
          [renderer media-renderer?]
          [uri string?]
          [#:metadata metadata string? ""]
          [#:next-uri next-uri (or/c #f string?) #f]
          [#:next-metadata next-metadata string? ""])
         any]{

Sets @racket[uri] as the current resource and starts playback.

When @racket[next-uri] is supplied, it is installed with
@tt{SetNextAVTransportURI} before playback starts.  A supporting renderer can
open and buffer the next resource while the current resource is playing,
allowing a gapless or near-gapless transition.
}

@defproc[(media-renderer-next-uri-supported?
          [renderer media-renderer?])
         boolean?]{

Reports whether the renderer advertises the optional
@tt{SetNextAVTransportURI} action.
}

@defproc[(media-renderer-set-next-uri!
          [renderer media-renderer?]
          [uri string?]
          [#:metadata metadata string? ""])
         any]{

Sets the resource that follows the currently playing resource.  The action
describes one next resource, not a complete queue.  After playback advances to
that resource, call this function again to preload the following track.
}

@defproc[(media-renderer-pause! [renderer media-renderer?]) any]
@defproc[(media-renderer-stop! [renderer media-renderer?]) any]
@defproc[(media-renderer-seek!
          [renderer media-renderer?]
          [seconds exact-nonnegative-integer?])
         any]
@defproc[(media-renderer-status [renderer media-renderer?]) symbol?]
@defproc[(media-renderer-position [renderer media-renderer?])
         transport-position?]

@defproc[(transport-position-track
          [position transport-position?])
         exact-nonnegative-integer?]
@defproc[(transport-position-seconds
          [position transport-position?])
         (or/c #f number?)]
@defproc[(transport-position-duration
          [position transport-position?])
         (or/c #f number?)]
@defproc[(transport-position-uri
          [position transport-position?])
         (or/c #f string?)]

@section{Volume and mute}

@defproc[(media-renderer-volume [renderer media-renderer?])
         exact-nonnegative-integer?]
@defproc[(media-renderer-set-volume!
          [renderer media-renderer?]
          [volume exact-nonnegative-integer?])
         any]
@defproc[(media-renderer-muted? [renderer media-renderer?]) boolean?]
@defproc[(media-renderer-set-muted!
          [renderer media-renderer?]
          [muted? boolean?])
         any]