[FFmpeg-devel,5/5] ffserver: Add basic documentation of the architecture

Submitted by Stephan Holljes on May 10, 2018, 3:41 p.m.

Details

Message ID 20180510154126.30789-6-klaxa1337@googlemail.com
State New
Headers show

Commit Message

Stephan Holljes May 10, 2018, 3:41 p.m.
Signed-off-by: Stephan Holljes <klaxa1337@googlemail.com>
---
 Documentation.txt | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 Documentation.txt

Comments

Moritz Barsnick May 11, 2018, 12:54 p.m.
On Thu, May 10, 2018 at 17:41:26 +0200, Stephan Holljes wrote:
> +In its current for this is a HTTP live-streaming server. A media file can be
                    ^ form    ^ an

> +streamed to a number of clients with the correct media file being muxed on-
> +the-fly for each client starting at the current position in the stream.

I don't understand: What's "correct"? And what is the "current
position"? From ffserver's point of view: The position if progressed to
between launch and connection of client?

> +The stream received by the clients is simply a HTTP response to an HTTP
                                                ^ an               ^ here, it's correct ;-)

> +is answered with a HTTP 400 error.
                    ^ an

Moritz
Stephan Holljes May 11, 2018, 1:19 p.m.
On Fri, May 11, 2018 at 2:54 PM, Moritz Barsnick <barsnick@gmx.net> wrote:
> On Thu, May 10, 2018 at 17:41:26 +0200, Stephan Holljes wrote:
>> +In its current for this is a HTTP live-streaming server. A media file can be
>                     ^ form    ^ an
>
>> +streamed to a number of clients with the correct media file being muxed on-
>> +the-fly for each client starting at the current position in the stream.
>
> I don't understand: What's "correct"? And what is the "current
> position"? From ffserver's point of view: The position if progressed to
> between launch and connection of client?

"correct" was probably the wrong word here. I have replaced it locally
by "a proper" instead of "the correct", although it feels unnecessary
in general. I might reword this.
The "current position" is, as you described, the position ffserver has
progressed to with reading the input since starting the program +
configurable buffering (so client's don't "stutter" during playback).
I will try to make that a bit clearer.

>
>> +The stream received by the clients is simply a HTTP response to an HTTP
>                                                 ^ an               ^ here, it's correct ;-)
>
>> +is answered with a HTTP 400 error.
>                     ^ an

I noticed these right before going to bed last night as well, fixed.

>
> Moritz
> _______________________________________________
> ffmpeg-devel mailing list
> ffmpeg-devel@ffmpeg.org
> http://ffmpeg.org/mailman/listinfo/ffmpeg-devel

Thanks again!

Patch hide | download patch | download mbox

diff --git a/Documentation.txt b/Documentation.txt
new file mode 100644
index 0000000..5b52c89
--- /dev/null
+++ b/Documentation.txt
@@ -0,0 +1,84 @@ 
+About
+-----
+
+In its current for this is a HTTP live-streaming server. A media file can be
+streamed to a number of clients with the correct media file being muxed on-
+the-fly for each client starting at the current position in the stream.
+The stream received by the clients is simply a HTTP response to an HTTP
+request.
+
+
+Documentation
+-------------
+
+The current implementation has three different types of work that is done in
+different threads. These types are: reading a stream, accepting HTTP
+connections and writing media data to clients.
+
+The design tries to follow a Publisher-Subscriber-Pattern. The PublisherContext
+struct contains buffers of read media data and the list of clients. Clients
+themselves contain a buffer of media data that still has to be sent to them.
+
+The reading thread takes care of segmenting the stream into independent chunks
+of data and pushing it to the PublisherContext, which publishes the new Segment
+to connected clients. This publishing only adds this Segment to the client's
+buffer.
+
+The writing thread does the actual writing of data over the network. It checks
+each client's state and if there is data available that can be written to that
+client it is sent.
+
+The accept thread accepts new clients over HTTP and if not all client slots are
+in use, writes the stream-header and adds the client to the PublisherContext.
+
+A Segment is only stored in memory once and is refcounted. Buffers in the
+PublisherContext and clients contain pointers to Segments.
+
+Buffers are implemented using AVFifoBuffer.
+
+Client states are protected by pthread-mutex-locks, making it possible to run
+multiple write threads.
+
+HTTPD-API
+---------
+
+To be independent of a specific http server implementation, an interface is
+provided that an http server implementation has to provide. At the time of
+writing an implementation using the libavformat http server is provided.
+
+The HTTPDInterface struct takes the following function pointers:
+
+struct HTTPDInterface {
+    int (*init)  (void **server, struct HTTPDConfig config);
+    int (*free)  (void *server);
+    int (*accept)(void *server, struct HTTPClient **client, int reply_code);
+    int (*write) (void *server, struct HTTPClient *client, const unsigned char *buf, int size);
+    int (*read)  (void *server, struct HTTPClient *client, unsigned char *buf, int size);
+    void (*close)(void *server, struct HTTPClient *client);
+    void (*shutdown)(void *server);
+};
+
+
+Usage
+-----
+
+Currently streams can be supplied as a stream through stdin or any ffmpeg-
+compatible URI, e.g. files or network locations. Examples:
+
+cat somefile.mkv | ./ffserver
+
+./ffserver somefile.mkv
+
+./ffserver http://somehost/somefile.mkv
+
+This will start reading the file and open port 8080 for HTTP client connections.
+The stream is read in real time from whatever resource it is retrieved.
+Currently a maximum of 16 clients is implemented.
+
+The server responds to any GET request with the mediastream. Any other request
+is answered with a HTTP 400 error.
+If the maximum number of clients is reached the server responds with a 503 HTTP
+error if a new client wants to connect.
+
+Once the stream ends the server will write all the remaining data to all
+connected clients before closing the connections and exiting.