Tutorials update WIP

Author: Noarkhh

broadcasting/03_RTMP_SystemArchitecture.md renamed to broadcasting/03_RTMP_Architecture.md

@@ -1,17 +1,15 @@
 # Architecture
 
 Now let's discuss how the architecture of our solution will look like.
-It will be a little different from the RTMP to HLS architecture.
-The main component will be the pipeline, which will ingest RTP stream and convert it to HLS. Beyond that we will also need a Connection Manager, which will be responsible for establishing an RTSP connection with the server.
+It will be a little different from the RTMP to HLS architecture. In most cases communication with a RTSP server is split into two phases:
 
-![image](assets/rtsp_architecture.drawio.png)
+- Negotiation of the stream parameters over RTSP.
+- Receiving RTP stream(s) that the client and server have agreed upon.
 
-When initializing, the pipeline will start a Connection Manager which starts an RTSP connection with the server. Once the connection is fully established, the pipeline will be notified.
+Both of these phases are handled by RTSP Source. Let's take a closer look how each of them folds out:
 
-Let's take a closer look on each of those components:
-
-## Connection Manager
-The role of the connection manager is to initialize RTSP session and start playing the stream.
+## Establishing the connection
+When establishing a connection the source will act as a connection manager, initializing the RTSP session and starting the stream playback.
 It communicates with the server using the [RTSP requests](https://antmedia.io/rtsp-explained-what-is-rtsp-how-it-works/#RTSP_requests). In fact, we won't need many requests to start playing the stream - take a look at the desired message flow:
 
 ![image](assets/connection_manager.drawio.png)
@@ -20,18 +18,21 @@ First we want to get the details of the video we will be playing, by sending the
 Then we call the `SETUP` method, defining the transport protocol (RTP) and client port used for receiving the stream.
 Now we can start the stream using `PLAY` method.
 
-## Pipeline
+## Receiving the stream
 
-The pipeline consists of a couple elements, each of them performing a specific media processing task. You can definitely notice some similarities to the pipeline described in the [RTMP architecture](02_RTMP_Introduction.md). However, we will only be processing video so only the video processing elements will be necessary.
+The source is a bin containing a few elements, each of them performing a specific media processing task. You can definitely notice some similarities to the pipeline described in the [RTMP architecture](02_RTMP_Introduction.md). However, we will only be processing video so only the video processing elements will be necessary.
 
 ![image](assets/rtsp_pipeline.drawio.png)
 
-We have already used the, `H264 Parser`, `MP4 H264 Payloader`, `CMAF Muxer` and `HLS Sink` elements in the RTMP pipeline, take a look at the [RTMP to HLS architecture](03_RTMP_SystemArchitecture.md) chapter for details of the purpose of those elements.
+We have already used the, `H264 Parser` and `HLS Sink Bin` elements in the RTMP pipeline, take a look at the [RTMP to HLS architecture](03_RTMP_SystemArchitecture.md) chapter for details of the purpose of those elements.
 
 Let us describe briefly what is the purpose of the other components:
 
 ### UDP Source
 This element is quite simple - it receives UDP packets from the network and sends their payloads to the next element.
 
-### RTP SessionBin
-RTP SessionBin is a Membrane's Bin, which is a Membrane's container used for creating reusable groups of elements. In our case the Bin handles the RTP session with the server, which has been set up by the Connection Manager.
+### RTP Demuxer
+This element is responsible for getting media packets out of the RTP packets they were transported in and routing them according to their [SSRC](https://datatracker.ietf.org/doc/html/rfc3550#section-3). In our case we only receive a single video stream, so only one output will be used.
+
+### RTP H264 Depayloader
+When transporting H264 streams over RTP they need to be split into chunks and have some additional metadata included. This element's role is to unpack the RTP packets it receives from the Demuxer into a pure H264 stream that can be processed further.

broadcasting/04_RTMP_RunningTheDemo.md renamed to broadcasting/04_RTMP_Running_The_Demo.md

@@ -1,53 +1,43 @@
 In the tutorial we won't explain how to implement the solution from the ground up - instead, we will run the existing code from [Membrane demos](https://github.com/membraneframework/membrane_demo).
 
 To run the RTSP to HLS converter first clone the demos repo:
-```console
+```bash
 git clone https://github.com/membraneframework/membrane_demo.git
 ```
 
-```console
+```bash
 cd membrane_demo/rtsp_to_hls
 ```
 
 Install the dependencies
-```console
+```bash
 mix deps.get
 ```
 
-Make sure you have those libraries installed as well:
-- gcc
-- libc-dev
-- ffmpeg
-
-On ubuntu:
-```console
-apt-get install gcc libc-dev ffmpeg
-```
-
 Take a look inside the `lib/application.ex` file. It's responsible for starting the pipeline.
 We need to give a few arguments to the pipeline:
 ```elixir
-@rtsp_stream_url "rtsp://rtsp.membrane.work:554/testsrc.264"
-@output_path "hls_output"
-@rtp_port 20000
+rtsp_stream_url = "rtsp://localhost:30001"
+output_path = "hls_output"
+rtp_port = 20000
 ```
 
-The `@output_path` attribute defines the storage directory for hls files and the `@rtp_port` defines on which port we will be expecting the rtp stream, once the RTSP connection is established.
+The `output_path` attribute defines the storage directory for hls files and the `rtp_port` defines on which port we will be expecting the rtp stream, once the RTSP connection is established.
 
-The `@rtsp_stream_url` attribute contains the address of the stream, which we will be converting. It is a sample stream prepared for the purpose of the demo. 
+The `rtsp_stream_url` attribute contains the address of the stream, which we will be converting. If you want to receive a stream from some accessible RTSP server, you can pass it's URL here. In this demo we'll run our own, simple server: 
+
+```bash
+mix run server.exs
+```
 
 Now we can start the application:
-```console
+```bash
 mix run --no-halt
 ```
 
-The pipeline will start playing, after a couple of seconds the HLS files should appear in the `@output_path` directory. In order to play the stream we need to first serve them. We can do it using simple python server.
-
-```console
-python3 -m http.server 8000
-```
+The pipeline will start playing, after a couple of seconds the HLS files should appear in the `@output_path` directory.
 
 Then we can play the stream using [ffmpeg](https://ffmpeg.org/), by pointing to the location of the manifest file:
-```console
+```bash
 ffplay http://YOUR_MACHINE_IP:8000/rtsp_to_hls/hls_output/index.m3u8
 ```

broadcasting/08_RTSP_Architecture.md

@@ -1,46 +1,54 @@
-As explained in the [Architecture chapter](08_RTSP_Architecture.md), the pipeline will consist of a couple of elements, that will be processing the RTP stream.
+As explained in the [Architecture chapter](08_RTSP_Architecture.md), the pipeline will consist of a RTSP Source and a HLS Sink.
 
-The flow of the pipeline will consist of three steps. First, when the pipeline is initialized we will start the Connection Manager, which will set up the RTP stream via the RTSP.
-Once that is finished, we will set up two initial elements in the pipeline - the `UDP Source` and `RTP SessionBin`, which will allow us to receive RTP packets and process them.
-When the SessionBin detects that the RTP stream has been started, it will notify the pipeline with the `:new_rtp_stream` notification. Later on, we will add the remaining elements to the pipeline, allowing for the whole conversion process to take place.
+The initial pipeline will consist only of the `RTSP Source` and it'll start establishing the connection with the RTSP server.
 
-Those steps take place, respectively, in the: `handle_init/1`, `handle_other/3` and `handle_notification/4` callbacks. While the `handle_init/1` is rather intuitive, we will describe in detail what's happening in the other callbacks.
+<!--The flow of the pipeline will consist of three steps. First, when the pipeline is initialized we will start the Connection Manager, which will set up the RTP stream via the RTSP.-->
+<!--Once that is finished, we will set up two initial elements in the pipeline - the `UDP Source` and `RTP SessionBin`, which will allow us to receive RTP packets and process them.-->
+<!--When the SessionBin detects that the RTP stream has been started, it will notify the pipeline with the `:new_rtp_stream` notification. Later on, we will add the remaining elements to the pipeline, allowing for the whole conversion process to take place.-->
 
-Let us explain what's going on in the `handle_other` callback:
+<!--Those steps take place, respectively, in the: `handle_init/1`, `handle_other/3` and `handle_notification/4` callbacks. While the `handle_init/1` is rather intuitive, we will describe in detail what's happening in the other callbacks.-->
+
+<!--Let us explain what's going on in the `handle_other` callback:-->
 
 ##### lib/pipeline.ex
 ```elixir
 @impl true
-def handle_other({:rtsp_setup_complete, options}, _ctx, state) do
-  children = %{
-    app_source: %Membrane.UDP.Source{
-      local_port_no: state[:port],
-      recv_buffer_size: 500_000
-    },
-    rtp: %Membrane.RTP.SessionBin{
-      fmt_mapping: %{96 => {:H264, 90_000}}
-    },
-    hls: %Membrane.HTTPAdaptiveStream.Sink{
-      manifest_module: Membrane.HTTPAdaptiveStream.HLS,
-      target_window_duration: 120 |> Membrane.Time.seconds(),
-      target_segment_duration: 4 |> Membrane.Time.seconds(),
-      storage: %Membrane.HTTPAdaptiveStream.Storages.FileStorage{
-        directory: state[:output_path]
-      }
-    }
-  }
+def handle_init(_context, options) do
+Logger.debug("Source handle_init options: #{inspect(options)}")
+
+spec = [
+  child(:source, %Membrane.RTSP.Source{
+    transport: {:udp, options.port, options.port + 5},
+    allowed_media_types: [:video, :audio],
+    stream_uri: options.stream_url,
+    on_connection_closed: :send_eos
+  })
+]
 
-  links = [
-    link(:app_source)
-    |> via_in(Pad.ref(:rtp_input, make_ref()))
-    |> to(:rtp)
-  ]
+{[spec: spec],
+  %{
+    output_path: options.output_path,
+    parent_pid: options.parent_pid,
+    tracks_left_to_link: nil,
+    track_specs: []
+  }}
+end
+```
+
+Once we receive the `{:set_up_tracks, tracks}` notification from the source we have the information what tracks have been set up during connection establishment and what we should expect. We take this information and store it, so that we link the source to the `HLS Sink Bin` correctly.
+
+```elixir
+@impl true
+def handle_child_notification({:set_up_tracks, tracks}, :source, _ctx, state) do
+  tracks_left_to_link =
+    [:audio, :video]
+    |> Enum.filter(fn media_type -> Enum.any?(tracks, &(&1.type == media_type)) end)
 
-  spec = %ParentSpec{children: children, links: links}
-  { {:ok, spec: spec}, %{state | video: %{sps: options[:sps], pps: options[:pps]}} }
+  {[], %{state | tracks_left_to_link: tracks_left_to_link}}
 end
 ```
 
+When a `PLAY` request is eventually sent by the source, we should be prepared to receive streams that have been set up. When a new RTP stream is received and identified by the source, a message is set to the parent - the pipeline in our case - containing information necessary to handle the stream.
 When we receive the `rtsp_setup_complete` message, we first define the new children for the pipeline, and links between them - the UDP Source and the RTP SessionBin. We also create the HLS Sink, however we won't be linking it just yet. With the message we receive the sps and pps inside the options, and we add them to the pipeline's state.
 
 Only after we receive the `:new_rtp_stream` notification we add the rest of the elements and link them with each other: