Merge pull request #23 from membraneframework/improve-headers-structure

Improve headers structure

Author: varsill

create_new_plugin/create_new_plugin.md

@@ -1,10 +1,10 @@
-# Creating your own plugin
+# Create your own plugin
 
 During the development of Membrane Framework we aim at designing fewer, but higher quality plugins. However, we also kept extendability and reusability in mind. That's why it is easy for developers like you to create their own custom plugin, which satisfies their needs.
 
 In this short guide we provide you with an overview of how to create your own Membrane plugin and how to integrate it into your project.
 
-# Membrane plugin template
+## Membrane plugin template
 
 To create a new plugin, we recommend using the [template](https://github.com/membraneframework/membrane_template_plugin) that has been made for this very purpose and which will be the base of your plugin.
 It defines necessary dependencies as well as other project specs, e.g. formatting, and guarantees you compliance with other Membrane components.

get_started/simple_pipeline.md renamed to get_started_with_membrane/get_started_with_membrane.md

@@ -50,7 +50,7 @@ That might not look too simple for now but don't worry, there'll be a lot of new
 
 The code above is one of the simplest examples of Membrane usage. It plays an mp3 file through your device's `portaudio`. Let's make it work.
 
-### Prerequisites
+## Prerequisites
 
 First we need to get all the libraries that Membrane needs to operate in our case. You can read about them more if you'd like, but for now we'll just jump to installation:
 
@@ -65,7 +65,7 @@ $ brew install clang-format portaudio ffmpeg libmad pkg-config
 
 Alternatively, you can use our docker image that already contains all libraries you need to smoothly run any membrane code. You can read more about how to do it [here](https://tutorials.membraneframework.org/tutorials/videoroom/2_EnvironmentPreparation.html#setting-environment-with-the-use-of-docker).
 
-### Creating a Project
+## Creating a Project
 
 By installing Elixir you'll get a bunch of useful tools. One of them is [Mix](https://hexdocs.pm/mix/Mix.html). As you can read in its documentation preface:
 > Mix is a build tool that provides tasks for creating, compiling, and testing Elixir projects, managing its dependencies, and more.
@@ -91,11 +91,11 @@ defp deps do
   ]
 end
 ```	
-### Our first Pipeline
+## Our first Pipeline
 
 The pipeline is one of the basic concepts of Membrane. It's a schema of how the data packets are flowing through our application.
 
-#### Pipeline behaviour
+### Pipeline behaviour
 
 Let's start with declaring that we'll be using the `Membrane.Pipeline` behaviour:
 
@@ -127,7 +127,7 @@ Since we want to spawn children processes and link them, we will use the [`spec_
 
 >If the concept of callbacks and behaviours is new to you, you should probably take some time to read about OTP in Elixir (especially the part starring GenServer and Supervisor). You can find the proper guide [here](https://elixir-lang.org/getting-started/mix-otp/agent.html)
 
-#### Elements
+### Elements
 
 The elements we'd like to use to play our mp3 will be:
 
@@ -157,7 +157,7 @@ children = %{
 
 The keys in the `children` keyword list (`file`, `decoder`, `converter`, `portaudio`) are just convenient names we gave our elements to refer to them later. We're going to need them for linking.
 
-#### Linking elements
+### Linking elements
 
 Now we should link them in the proper order. Each Membrane Element can be one of three types: Source, Sink or Filter. The main difference is that Source provides only output pads, Sink only input and Filter both input and output pads. That means only a Source element start pipelines (it's not prepared to receive any data from other elements), Sink can only end pipelines (it will not send any data to subsequent elements), and Filters can be in the middle (they receive, process and send data further). In our case the links declaration will look like this: 
 
@@ -172,7 +172,7 @@ links = [
 
 The file Source reads bytes from our mp3 file and sends them to decoder. Decoder, after decoding, sends them to converter. Converter, after conversion sends them to our portaudio sink, which receives them and plays music through Portaudio 🎶
 
-#### Parent Spec
+### Parent Spec
 
 Last but not least we need group our elements and links together into a proper structure:
 
@@ -225,7 +225,7 @@ defmodule Hello do
 end
 ```
 
-### Running a pipeline
+## Running a pipeline
 
 You can start your pipeline from any place in the code but it's convenient to use Elixir's interactive console:
 

glossary/glossary.md

@@ -1,3 +1,4 @@
+# Glossary
 ## Multimedia 
 + <a name="packet"></a> **Packet** is a formatted unit of data transmitted over network. In order to send data over network it has to be fragmented into packets, which size is limited by [MTU(Maximum Transfer Unit)](https://en.wikipedia.org/wiki/Maximum_transmission_unit) - 1500 bytes when using [Ethernet](https://en.wikipedia.org/wiki/Ethernet_frame).
 + <a name="frame"></a> **Frame** can refer to either [network frame](https://en.wikipedia.org/wiki/Frame_(networking)) or **media frame**, which is a basic data unit used by media coding formats. In particular one media frame can represent a single image in a video.
@@ -31,7 +32,6 @@
   + <a name="mcu"></a> **MCU**([Multipoint Control Unit](https://millo-l.github.io/WebRTC-implementation-method-Mesh-SFU-MCU/#23-mcumulti-point-control-unit-server)) is an architecture consisting of a single server, which receives incoming streams from all participants, mixes the streams, and sends them to each of the participants.
   + <a name="p2p"></a> **P2P**([Peer to Peer](https://millo-l.github.io/WebRTC-implementation-method-Mesh-SFU-MCU/#21-signaling-serverp2pmesh)) is an architecture in which each participant is directly connected to all other participants, which eliminates the need for MCU or SFU.
 
-
 ## Membrane Framework 
 + <a name="pad"></a> **Pad** is an input or output of an [elements](#element) or a [bin](#bin). Output pads of one element are connected to input pads of another element or bin.
 + <a name="caps"></a> **Caps**(abbr. from capabilities) define [pads](#pad) specification, allowing us to determine whether two elements are compatible with each other. 

videoroom/1_Introduction.md

@@ -9,8 +9,10 @@ description: >-
 github.repository_url: https://github.com/membraneframework/membrane_mp4_plugin
 ---
 
-The scope of this tutorial covers the process of creating your own video room with the use of the Membrane framework.
 # Introduction
+The scope of this tutorial covers the process of creating your own video room with the use of the Membrane framework.
+
+## What are we doing here?
 It hasn't been that long ago when video rooms have become quite a common tool used in many fields of our life. We use them when we want to have an impression of meeting our beloved ones in the manner as they were sitting just next to us. We use them at work, to synchronize our work progress and exchange information between us and our colleagues.
 Taking advantage of recent technological improvements and state-of-the-art tools introduced in the field of data transmission, video streaming
 has become accessible to everyone at the scale not known previously.

videoroom/2_EnvironmentPreparation.md

@@ -7,14 +7,14 @@ description: >-
   <br> <b>Forum:</b> <a style="color: white" href=https://elixirforum.com/c/elixir-framework-forums/membrane-forum/104/>Membrane Forum</a>
   </div>
 ---
-# Getting started
+# Environment preparation
 
 ## Elixir installation
- I don't think I can describe it any better: [How to install Elixir](https://elixir-lang.org/install.html).
- But do not forget to add the elixir bin to your PATH variable!
+I don't think I can describe it any better: [How to install Elixir](https://elixir-lang.org/install.html).
+But do not forget to add the elixir bin to your PATH variable!
 
- Take your time and make yourself comfortable with Elixir. Check if you can run Elixir's interactive terminal and if you can compile Elixir's source files with the Elixir compiler.
- You can also try to create a new Mix project - we will be using [Mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) as the build automation tool all along with the tutorial.
+Take your time and make yourself comfortable with Elixir. Check if you can run Elixir's interactive terminal and if you can compile Elixir's source files with the Elixir compiler.
+You can also try to create a new Mix project - we will be using [Mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) as the build automation tool all along with the tutorial.
 
 ## Template downloading
 Once we have the development environment set up properly (let's hope so!) we can start to work on our project. We don't want you to do it from scratch as the development requires some dull playing around with UI, setting the dependencies, etc. - we want to provide you only the meat! That is why we would like you to download the template project with core parts of the code missing. You can do it by typing:
@@ -32,24 +32,24 @@ git checkout template/start
 
 In case you find yourself lost along with the tutorial, feel free to check the suggested implementation provided by us, which is available on the `template/end` branch of this repository.
 
-# Install native dependencies
+## Native dependencies installing
 First, some native dependencies are needed. Here is how you can install them and setup the required environment variables.
 
-## Mac OS with M1
+### Mac OS with M1
 ```
 brew install node srtp libnice clang-format ffmpeg
 export C_INCLUDE_PATH=/opt/homebrew/Cellar/libnice/0.1.18/include:/opt/homebrew/Cellar/opus/1.3.1/include:/opt/homebrew/Cellar/[email protected]/1.1.1l_1/include
 export LIBRARY_PATH=/opt/homebrew/Cellar/opus/1.3.1/lib
 export PKG_CONFIG_PATH=/opt/homebrew/Cellar/[email protected]/1.1.1l_1/lib/pkgconfig/
 ```
 
-## Mac OS with Intel
+### Mac OS with Intel
 ```
 brew install node srtp libnice clang-format ffmpeg
 export PKG_CONFIG_PATH="/usr/local/opt/[email protected]/lib/pkgconfig"
 ```
 
-## Ubuntu
+### Ubuntu
 
 ```
 sudo apt-get install npm build-essential pkg-config libssl-dev libopus-dev libsrtp2-dev libnice-dev libavcodec-dev libavformat-dev libavutil-dev
@@ -61,7 +61,7 @@ If you installed Elixir from ESL repo, make sure the following erlang packages a
 sudo apt-get install erlang-dev erlang-parsetools erlang-src
 ```
 
-# Setting environment with the use of Docker
+### Setting environment with the use of Docker
 Alternatively to the steps described in the section above, you can make use of the docker image we have prepared for the purpose of this tutorial.
 You won't need to install any native dependencies there nor export environmental variables - however **your computer cannot be running on M1 processor**.
 
@@ -83,49 +83,49 @@ docker run -p 4000:4000 -it -v `pwd`:/videoroom membraneframeworklabs/docker_mem
 
 After running the command, a container terminal will be attached to your terminal. You will be able to find the project code inside the container in the `/videoroom` directory.
 
-# What do we have here?
- Let's make some reconnaissance.
- First, let's run the template.
- Before running the template we need to install the dependencies using:
- ```
- mix deps.get
- npm ci --prefix=assets
- ```
-
- Then you can simply run the Phoenix server with the following command:
- ```
- mix phx.server
- ```
- If everything went well the application should be available on [http://localhost:4000](http://localhost:4000/).
-
- Play around...but it is not that much to do! We have better inspect what is the structure of our project.
- Does the project structure reassemble you the structure of a Phoenix project? (in fact, it should!). We will go through the directories in our project.
- + **assets/** <br>
- You can find the front end of our application. The most interesting subdirectory here is src/ - we will be putting our typescript files there. For now, the following files should be present there:
-   + **consts.ts** - as the name suggests, you will find there some constant values - media constrains and our local peer id
-   + **index.ts** - this one should be empty. It will act as an initialization point for our application and later on, we will spawn a room object there.
-   + **room_ui.ts** - methods which modify DOM are put there. You will find these methods helpful while implementing your room's logic - you will be able to simply call a method in order to put a next video tile among previously present video tiles and this whole process (along with rescaling or moving the tiles so they are nicely put on the screen) will be performed automatically
- + **config/** <br>
- Here you can find configuration files for given environments. There is nothing we should be interested in.
- + **deps/** <br>
- Once you type ```mix deps.get``` all the dependencies listed in mix.lock file will get downloaded and be put into this directory. Once again - this is just how mix works and we do not care about this directory anyhow.
- + **lib/** <br>
- This directory contains the server's logic. As mentioned previously, the Phoenix server implements Model-View-Controller architecture so the structure of this directory will reflect this architecture.
- The only .ex file in this directory is `videoroom_web.ex` file - it defines the aforementioned parts of the system - **controller** and **view**. Moreover,
- it defines ```router``` and ```channel``` - the part of the system which is used for communication. This file is generated automatically with the Phoenix project generator
- and there are not that many situations in which you should manually change it.
-   + **videoroom/** <br>
-   This directory contains the business logic of our application, which stands for M (model) in MVC architecture. For now, it should only contain application.ex file which defines the Application module for our video room. As each [application](https://hexdocs.pm/elixir/1.12/Application.html), it can be loaded, started, and stopped, as well as it can bring to life its own children (which constitute the environment created by an application). Later on, we will put into this directory files which will provide some logic of our application - for instance, Videoroom.Room module will be defined there.
-   + **videoroom_web/**<br>
-   This directory contains files that stand for V (view) and C (controller) in the MVC architecture.
-   As you can see, there are already directories with names "views" and "controllers" present here. The aforementioned (tutorial) (the one available in the "helpful links" sections) describes the structure and contents of this directory in a really clear way so I don't think there is a need to repeat this description here. The only thing I would like to point out is the way in which we are loading our custom Javascript scripts. Take a look at lib/videoroom_web/room/index.html.eex file (as the Phoenix tutorial says, this file should contain an EEx template for your room controller ) - you will find the following line there:
-   ```html
-   <script src="<%= static_path(@conn, "/js/room.js") %>"></script>
-   ```
-   As you can see, we are loading a script which is placed in `/js/room.js` (notice, that a path provided there is passed in respect to priv/static/ directory which holds files generated from typescript scripts in assets/src/ directory)
-
- + **priv/static/** <br>
- Here you will find static assets. They can be generated, for instance, from the files contained in assets/ directory (.ts which are in assets/src are converted into .js files put inside priv/static/js). Not interesting at all, despite the fact, that we needed to load /js/room.js script file from here ;)
+## What do we have here?
+Let's make some reconnaissance.
+First, let's run the template.
+Before running the template we need to install the dependencies using:
+```
+mix deps.get
+npm ci --prefix=assets
+```
+
+Then you can simply run the Phoenix server with the following command:
+```
+mix phx.server
+```
+If everything went well the application should be available on [http://localhost:4000](http://localhost:4000/).
+
+Play around...but it is not that much to do! We have better inspect what is the structure of our project.
+Does the project structure reassemble you the structure of a Phoenix project? (in fact, it should!). We will go through the directories in our project.
++ **assets/** <br>
+You can find the front end of our application. The most interesting subdirectory here is src/ - we will be putting our typescript files there. For now, the following files should be present there:
+  + **consts.ts** - as the name suggests, you will find there some constant values - media constrains and our local peer id
+  + **index.ts** - this one should be empty. It will act as an initialization point for our application and later on, we will spawn a room object there.
+  + **room_ui.ts** - methods which modify DOM are put there. You will find these methods helpful while implementing your room's logic - you will be able to simply call a method in order to put a next video tile among previously present video tiles and this whole process (along with rescaling or moving the tiles so they are nicely put on the screen) will be performed automatically
++ **config/** <br>
+Here you can find configuration files for given environments. There is nothing we should be interested in.
++ **deps/** <br>
+Once you type ```mix deps.get``` all the dependencies listed in mix.lock file will get downloaded and be put into this directory. Once again - this is just how mix works and we do not care about this directory anyhow.
++ **lib/** <br>
+This directory contains the server's logic. As mentioned previously, the Phoenix server implements Model-View-Controller architecture so the structure of this directory will reflect this architecture.
+The only .ex file in this directory is `videoroom_web.ex` file - it defines the aforementioned parts of the system - **controller** and **view**. Moreover,
+it defines ```router``` and ```channel``` - the part of the system which is used for communication. This file is generated automatically with the Phoenix project generator
+and there are not that many situations in which you should manually change it.
+  + **videoroom/** <br>
+  This directory contains the business logic of our application, which stands for M (model) in MVC architecture. For now, it should only contain application.ex file which defines the Application module for our video room. As each [application](https://hexdocs.pm/elixir/1.12/Application.html), it can be loaded, started, and stopped, as well as it can bring to life its own children (which constitute the environment created by an application). Later on, we will put into this directory files which will provide some logic of our application - for instance, Videoroom.Room module will be defined there.
+  + **videoroom_web/**<br>
+  This directory contains files that stand for V (view) and C (controller) in the MVC architecture.
+  As you can see, there are already directories with names "views" and "controllers" present here. The aforementioned (tutorial) (the one available in the "helpful links" sections) describes the structure and contents of this directory in a really clear way so I don't think there is a need to repeat this description here. The only thing I would like to point out is the way in which we are loading our custom Javascript scripts. Take a look at lib/videoroom_web/room/index.html.eex file (as the Phoenix tutorial says, this file should contain an EEx template for your room controller ) - you will find the following line there:
+  ```html
+  <script src="<%= static_path(@conn, "/js/room.js") %>"></script>
+  ```
+  As you can see, we are loading a script which is placed in `/js/room.js` (notice, that a path provided there is passed in respect to priv/static/ directory which holds files generated from typescript scripts in assets/src/ directory)
+
++ **priv/static/** <br>
+Here you will find static assets. They can be generated, for instance, from the files contained in assets/ directory (.ts which are in assets/src are converted into .js files put inside priv/static/js). Not interesting at all, despite the fact, that we needed to load /js/room.js script file from here ;)
 <br><br>
 [NEXT - System architecture](3_SystemArchitecture.md)<br>
 [PREV - Introduction](1_Introduction)<br>