Media file server

scribblings/media-renderer.scrbl

@@ -1,51 +1,114 @@
 #lang scribble/manual
 
-@(require (for-label racket/base
-                     racket/contract
-                     (file "../main.rkt")
-                     (file "../media-renderer.rkt")
-                     (file "../services/av-transport.rkt")))
+@(require
+  (for-label
+   racket/base
+   (file "../media-renderer.rkt")))
 
-@title{Media Renderer}
+@title{Media Renderers}
 
-@defmodule[@racketmodname[racket-upnp/media-renderer] #:module-paths ((file "../media-renderer.rkt"))]
+@defmodule[(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.
+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 upnp-device?)]{
-Discovers UPnP MediaRenderers. When @racket[dlna-only?] is true, only devices
-advertising an @tt{X_DLNADOC} value are returned.
+@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[(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.}
+@defproc[(get-media-renderer [filter-name string?])
+         (or/c #f media-renderer?)]{
 
-@section[#:tag "media-renderer-example"]{Example}
+Returns the first discovered renderer whose name contains
+@racket[filter-name], ignoring case, or @racket[#f] when no renderer matches.
+}
 
-@racketblock[
-(define renderer
-  (car (query-media-renderers #:interface "10.7.3.118")))
+@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?]
 
-(media-renderer-play-uri!
- renderer
- "http://10.7.3.32:50002/music/track.flac")
+@section{Playback}
 
-(media-renderer-set-volume! renderer 30)
-]
+@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]