#lang scribble/manual

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

@title{Media Renderer}

@defmodule[@racketmodname[racket-upnp/media-renderer] #:module-paths ((file "../media-renderer.rkt"))]

This module hides AVTransport and RenderingControl for common playback code.
The returned renderer remains an @racket[upnp-device?], so generic service
inspection is still available.

@defproc[(query-media-renderers [#:interface interface (or/c #f string?) #f]
                                [#:dns? dns? boolean? #f]
                                [#:dlna-only? dlna-only? boolean? #f])
         (listof upnp-device?)]{
Discovers UPnP MediaRenderers. When @racket[dlna-only?] is true, only devices
advertising an @tt{X_DLNADOC} value are returned.
}

@defproc[(media-renderer? [value any/c]) boolean?]{Recognises a MediaRenderer device.}
@defproc[(media-renderer-dlna? [renderer media-renderer?]) boolean?]{Reports whether the device description advertises a DLNA document identifier.}
@defproc[(media-renderer-play-uri! [renderer media-renderer?]
                                   [uri string?]
                                   [#:metadata metadata string? ""]) void?]{Sets the URI and starts playback.}
@defproc[(media-renderer-pause! [renderer media-renderer?]) void?]{Pauses playback.}
@defproc[(media-renderer-stop! [renderer media-renderer?]) void?]{Stops playback.}
@defproc[(media-renderer-seek! [renderer media-renderer?] [seconds nonnegative-real?]) void?]{Seeks to a relative time.}
@defproc[(media-renderer-status [renderer media-renderer?]) symbol?]{Returns the abstracted transport state.}
@defproc[(media-renderer-position [renderer media-renderer?]) transport-position?]{Returns current position information.}
@defproc[(media-renderer-volume [renderer media-renderer?]) (or/c #f exact-integer?)]{Returns the device-specific volume value.}
@defproc[(media-renderer-set-volume! [renderer media-renderer?] [volume (integer-in 0 65535)]) void?]{Sets the device-specific volume value.}
@defproc[(media-renderer-muted? [renderer media-renderer?]) boolean?]{Returns the mute state.}
@defproc[(media-renderer-set-muted! [renderer media-renderer?] [muted? boolean?]) void?]{Sets the mute state.}

@section[#:tag "media-renderer-example"]{Example}

@racketblock[
(define renderer
  (car (query-media-renderers #:interface "10.7.3.118")))

(media-renderer-play-uri!
 renderer
 "http://10.7.3.32:50002/music/track.flac")

(media-renderer-set-volume! renderer 30)
]