Media file server

2026-07-15 20:48:58 +02:00
parent c6954f5109
commit 1884008dd6
5 changed files with 349 additions and 138 deletions
@@ -0,0 +1,113 @@
+#lang scribble/manual
+
+@(require
+  (for-label
+   racket/base
+   (file "../media-file-server.rkt")))
+
+@title{Publishing Media Files}
+
+@defmodule[(file "../media-file-server.rkt")]
+
+This module publishes local files through a small Racket web server.  The
+underlying Racket file dispatcher streams files and supports both @tt{HEAD}
+requests and HTTP byte ranges.  Byte ranges are important for media-renderer
+probing and seeking.
+
+@defproc[(start-media-file-server
+          [url string?]
+          [#:listen-ip listen-ip (or/c #f string?) #f])
+         media-file-server?]{
+
+Starts a server for the HTTP origin and path prefix in @racket[url].
+The URL must be an absolute @tt{http://} URL.  A trailing slash is added when
+needed.
+
+When @racket[listen-ip] is @racket[#f], the server listens on all local
+interfaces.  Supply a local address, such as @tt{10.7.3.118}, to restrict the
+listener to that interface.
+}
+
+@defproc[(media-file-server-url
+          [server media-file-server?])
+         string?]{
+
+Returns the normalized base URL of @racket[server].
+}
+
+@defproc[(media-file-server-publish!
+          [server media-file-server?]
+          [file path-string?]
+          [url string?]
+          [#:mime-type mime-type (or/c #f bytes? string?) #f])
+         string?]{
+
+Publishes @racket[file] at @racket[url] and returns the absolute URL.
+
+The URL may be relative to the server URL:
+
+@racketblock[
+(define uri
+  (media-file-server-publish!
+   files
+   "C:/muziek/test.flac"
+   "test.flac"))
+]
+
+It may also be the complete URL, provided that its origin and path prefix match
+the server:
+
+@racketblock[
+(media-file-server-publish!
+ files
+ "C:/muziek/test.flac"
+ "http://10.7.3.118:8080/media/test.flac")
+]
+
+The MIME type is inferred for common audio, video, and image extensions.
+Use @racket[#:mime-type] to override it.
+}
+
+@defproc[(media-file-server-unpublish!
+          [server media-file-server?]
+          [url string?])
+         void?]{
+
+Removes the URL mapping.  Requests that are already in progress may still
+finish.
+}
+
+@defproc[(media-file-server-stop!
+          [server media-file-server?])
+         void?]{
+
+Stops the web server.  Repeated calls have no effect.
+}
+
+@section{Playing local files}
+
+@racketblock[
+(define files
+  (start-media-file-server
+   "http://10.7.3.118:8080/media/"
+   #:listen-ip "10.7.3.118"))
+
+(define first-uri
+  (media-file-server-publish!
+   files
+   "C:/muziek/first.flac"
+   "first.flac"))
+
+(define second-uri
+  (media-file-server-publish!
+   files
+   "C:/muziek/second.flac"
+   "second.flac"))
+
+(media-renderer-play-uri!
+ renderer
+ first-uri
+ #:next-uri second-uri)
+]
+
+Keep the URLs published until the renderer has finished reading them.