USER GUIDE version: demo
USER GUIDE version: demo
You have downloaded the archive, which contains all the files needed for the first launch and testing of Oja:
- oja-media-server - the media server itself;
- oja-media-server.config - file with server settings;
- oja-media-manager - server web interface engine;
- oja-media-manager.config - file with settings for the server web interface engine;
- big-buck-bunny.mkv - test video file which helps you to test vod sources;
Create a new folder and unpack the downloaded archive into it. Now you need to open a terminal (for Microsoft Windows - Windows Terminal or PowerShell) and launch the web interface and media server. To do this, create two tabs, go to each in this folder and launch the media server in the first tab, specifying it to the file with the settings:
- ./oja-media-server -config ./oja-media-server.config
- In the second tab- the web interface engine, specifying the file with the settings:
- ./oja-media-manager -config ./oja-media-manager.config
Done! Now you can open a page in your browser at http://localhost:18000 and go to the web interface. The default username is “admin”, the password is “admin”:
A bit later we'll go back to the overview of the web interface , meanwhile let's look at the general principle of operation. The media server is running, it is in standby mode - both media data from client devices and requests from the administrator - from you. The web interface engine runs up, analyzes its settings file, gets the network address of the media server and connects to it. After that, you can start to receive information about the state of the media server, configure it and track statistics on the use of physical resources. The media server will send you notifications about any errors or warnings, if there are any.
The server expects requests from the web interface on 0.0.0.0 (that is, on all listening network interfaces) and on port 18001. The web interface engine sends requests to the address 127.0.0.1 and port 18001, while expects requests from the user at address 0.0.0.0 and on port 18000. If you want to change these parameters, see sections 7 and 8.
You can run media server and web interface engine on different computers and even on different networks. For security reasons, all communication between the engine and the media server is encrypted by default and transmitted over the https protocol. You can also set up the startup parameters so that the media server can only receive requests from the internal network. However, we'll do it later, meanwhile let's move on to an overview of the web interface.
The web interface allows you to conveniently manage and configure the Oja Media Server, monitor load, and monitor client connections.
On the left is the interface menu, on the top is the username which was used for authentication, the network address of the Oja Media Server, and its status (online or offline).
On the main page of the web interface, you can track the total load on the server: percentage of CPU usage, RAM and swap usage, and incoming and outgoing throughput. This data is currently displayed at the top of the screen; below you can track them on the graph for the last minute. Bottom of the page you will find information about your license for Oja Media Server, its version and uptime.
Next are the Sources and Recorders menu items:
They contain tables with information about the created sources and recorders. There is an opportunity to get detailed information, change/delete their settings for each recorder or source. New sources or recorders can also be created there.
If there are any events related to sources or recorders, the web interface receives a notification in real time.You will always see up-to-date information without having to reload the page. Below is a list of these events:
- The source went from offline to online
- The source went from online to offline
- Source changed status: ok, warn or error
- The recorder has changed its state: waiting for online source, recording or stopping
- Recorder changed status: ok, warn or error
You can check more details about sources and recorders in sections 4 and 5.
In the following sections, you can configure the basic settings for protocols, containers, recorders and multicast:
The new settings will be applied immediately, you do not need to restart the Oja Media Server. You can see more information about basic Oja Media Server settings in section 7.
We call the source a certain record in the server configuration that specifies the parameters of working with clients. Sources are defined by their own type (Live or Vod) and unique name.
Clients interact with Oja through sources:
- while connecting to a video server, the client specifies the source where he wants to send the data;
- the connection parameters to an existing stream are specified in the context of a source;
- any player specifies the source he wants to receive data for playback;
In this screenshot, the player is connected to the source “Bunny”
Sources help manage user streams and sessions, differentiate and customize them. For example, you can create a video chat in which each registered user will have their own source, or an online cinema where each source will be a separate film.
A general URL query scheme to connect to a source for video transmission or playback is:
protocol://oja-addr:protocol-port/source-name[.extension]
protocol is the name of the protocol. Oja supports RTMP and RTSP protocols for receiving multimedia and RTMP, RTSP and HLS to send for playback. Just put the name of the protocol you want into the diagram. Please note that to play via HLS, you must specify HTTP, since HTTP is the basis of HLS (for more details, see section 1)
- rtmp://oja-addr:protocol-port/source-name
- rtsp://oja-addr:protocol-port/source-name
- http://oja-addr:protocol-port/source-name[.extension]
- oja-addr is the network address of the Oja Media server, for example my-videochat.com or192.168.0.100;
- protocol-port is the port on which Oja waits for clients to connect using the selected protocol. For moredetails see section 3;
- source-name is the name of the source, which is used for connection;
- [.extension] parameter for playing via HLS protocol. In this case, you must specify not only the source name, but also the playlist extension: source-name.m3u8. More details on playlists and generally on HLS are given in section 1;
For example, a full URL of Oja running on localhost to publish or play the source "test" via RTMP protocol with default values will looks like this:
rtmp://127.0.0.1:1935/test
It is one of the live streams in which Oja is in the public connection modeA request to play the same source using the HLS protocol:
http://127.0.0.1:8000/test.m3u8
Using the server’s web interface you can browse the list of sources, configure them, delete and create new ones. Let’s take a closer look at them.
As noted earlier, video-on-demand or VoD is a type of streaming where a client receives pre-recorded and saved material. When you watch a Youtube video or a Netflix show, you get a video on demand. In the default configuration, Oja already has one VoD source. This source is called vod-1, it contains standard settings and works with a test file that comes with Oja. This file contains media content that will be sent to clients. You can immediately start to watch the stream from this source: just connect by any player from any device and start to watch!
Of course, you can create your own VoD sources as well. Click Add Source, select the VoD source type and enter its name
Then you need to specify the path to the mkv file from which the content will be transmitted. Specify the full path in the path field and press Create.
Now you can also connect to your source and start playback. The size and duration of the video is irrelevant. Make sure that the file from which you are sending is not corrupted and has the necessary permissions. All VoDsource parameters are described in Part 7.
This is one of the types of live broadcasts, in which Oja is in standby mode for connecting publishers. There are sources created on the server and some clients can send multimedia and other clients can view it.
Such live-streams are familiar to us: video chats, video conferences, Periscope, Twitch - these and other services can be created on the passive source basis. Each passive source can have only one publisher, but any number of players.
To publish to the passive source it is necessary to have a software or device that supports sending multimedia via RTMP or RTSP protocol. For example, we can use OBS Studio (https://obsproject.com). Please, download, install and run this program. Select custom service and specify the following options:
- server address - request URL according to the protocol://oja-addr:protocol-port scheme. For example,for streaming via RTMP protocol to localhost, it will look like this: rtmp://localhost:1935
- the stream key is publish-1. This is a passive source that is specified in the standard Oja configuration.
Then click OK and set up OBS Studio’s audio and video sources as specified in the documentation: https://obsproject.com/wiki/Sources-Guide. For example, you can use your computer’s webcam and audio output.
After that, start streaming. OBS Studio will start sending media data to Oja using RTMP protocol, and then you will be able to connect to Oja and watch stream from any device and any protocol
You can connect to this source for playback in the same way as any other: just specify the source name and what protocol you want to use to start playback:
Don’t worry if your player is a little behind in time: most players contain a buffer for caching data. In other words, the player typically stores the data in the queue before decoding and playing it. This queue can be so big and reach a few seconds. Oja itself processes the data almost instantaneously.
Do not limit yourself to a webcam or a computer: you can use your smartphone to transmit media! Install an application suitable for you to shoot and publish, specify Oja address and start streaming.
Creating a new passive source is also very simple: click Add Source, select the Live source type and enter itsname and click Next:
You will go to the menu where you can set the settings you want. You can leave all the default settings and clickCreate. That's all, you’ve created a new source, and it’s ready to accept publications!
Using passive sources, you can create live streaming services and media platforms in which users will broadcast their own video content in real time.
What do we call an active source? This is a source that connects to an already existing stream. That means that Oja is the proactive party that initiates the connection itself. This stream can be transmitted by any device or software, for example, a video surveillance system or other media server. Let's imagine a web camera located on top of Mount Everest. This camera transmits video with a panorama of the Himalayas to the Internet. There are lots of people who want to see the world from a height of almost 9000 meters, but the camera won't be able to send the stream to everyone - first of all, because it has a slow Internet connection, which cannot handle a large number of clients. In this case, we can create a source on Oja, connect this source to the camera, start receiving a stream from it and transmit it to everyone in any part of the world. A camera will only have one client, while Oja may have thousands, but Oja is great at serving thousands of clients simultaneously!
Creating an active source is almost the same as creating a passive one: you need to click Add Source and specify the required parameters. The only difference is that you need to set the Active connection type parameter and then enter the URL where you can connect to the stream:
Let's try to connect to an existing stream that is being distributed by another media server. We will use the Live555 server (http://www.live555.com/), which can stream using the rtsp protocol. Go to the official website, download and install this server. Run it as mentioned in the documentation and make sure you can connect to it and view the stream
Then create a new active source in the Oja web interface and specify the URL where you want to connect to Live555:
Disable the immediately parameter to manage the connection manually. Done? Now get connected!
The source must be online:
That's all, now Oja is a streaming repeater, hundreds and thousands of clients can connect to it using any protocol and watch your video:
Try to connect to other streams: from media servers, from other Oja nodes, webcams, webcasts, and video surveillance systems.
Any live stream can be written to a file or other persistent storage. Recorders are used to control the recording. We can think of a recorder as a wrapper and link between the live source and the storage into which the stream is saved. This wrapper helps you set up and manage media recording.
Let's try to create a recorder. Follow the link Recorders and click on the Add recorder button.
You will be taken to a page with fields for setting up the new recorder. In Section 7 you can learn more about the meaning of each parameter, but for now let's take a look at the most important ones. The first thing to remember is the title, let's call our new recorder my-new-rec. Next, select the live source that we want to record: start typing the name of the desired source, which is offline. That's all for this button, now you can click Add Recorder. You will be taken back to the page with the list of recorders and the one you have just created.
Note that this recorder has a stop mode:
That means that even if the source is online, data will not be recorded. The stopped recorder does not write data and does not interact with the source at all. Click on the Start button:
What happened? The recorder has entered wait mode. This means that it is ready to record media data and is waiting for its source to go online.
Now let's start recording: start publishing or connect to url, depending on selected source. Our recorder automatically went into run mode and started writing data to the file. Wait a little, and then stop recording: click on the stop button. The recorder is disconnected; recording is stopped.
You can preview the file and make sure that all the necessary media data is recorded and saved.
Recorders can be created for both offline and online sources. Depending on the selected settings, recording will either start immediately after creation, or you will need to start it manually. Once the recorder is ready to record, you don't have to do anything else: the recording will automatically stop and resume depending on the online/offline status of the live source.
Create and tune recorders, manage recordings and be sure that you will not lose a single byte of the data you need!
Multicast - a form of broadcasting where a stream of udp packets is transmitted to a group of multiple clients in a multicast group. However, transmission control and multicast support are handled by routers, not by software application.
From Oja's point of view, it has only one client and one network connection to which the stream is sent. From the clients' point of view, they have one network connection from which they receive the stream. This can significantly reduce the load on the media server and intermediate network hardware.
However, multicast also has limitations, the main one of which is the impossibility of working on the open Internet. Unfortunately, multicast works on a specially configured local network only. If you still need to work over the Internet, then consider tunneling technologies.
Oja can send a multicast stream to any number of clients. To enable multicast from an existing live source or create a new source with pre-enabled multicast, go to the configuration and open the Multicast tab. Now we are interested in two parameters: Enable and Push. The first parameter is responsible for enabling and disabling multicast for this source - enable it. The second is the network address to which the multicast stream is sent. Enter the required address here with the udp prefix, for example, udp://224.2.2.4:12808
Save your settings and start publishing or connect to a stream, depending on your source type. Now try to connect to the multicast:
If you have any problems with playback, please make sure that your network connection parameters allow you to work with multicast. Some firewalls and routers may require additional configuration.
In this case, of course, other protocols will also be available.
You can find the rest of the multicast parameters in section 7.
You can customize Oja to achieve better performance, save hardware resources, and other goals you need.
There are two types of configuration, basic and local. The basic configuration is the default settings - the parameters with which new sources or recorders will be created, if you do not change something while creating them. The local configuration refers to a single entity, a source or a recorder. In other words, the local configuration can either completely match the base configuration or override it in any parameters.
You can override any basic configuration parameters for a new source or recorder. Default parameters are basic configuration.
We recommend you customise the basic configuration to suit most sources and medium-load recorders. Find the right mix of physical resources, productivity, and customer service. However, if a source differs from the others, it may need to override some settings. For example, if you have an online video service, then a VoD source with an expected blockbuster or the latest episode of a popular TV series will have more clients than others. In this case, you can reduce the load on the network and increase performance at the expense of saving RAM. Similar scenarios could be with a Live source that broadcasts the soccer championship final or a recorder that records a high frame rate stream.
Oja is waiting for incoming connections from clients at specific network addresses and ports. The default network address is 0.0.0.0 for all protocols. This address means that Oja will accept all incoming connections on all of its network interfaces. If you want to allow clients to connect only from a specific network, change the 0.0.0.0 address to the one you need.
For more details on the network addresses see RFC 5735
Each protocol has a port on which connections are expected. For RTMP, the default port is 1935, for RTSP - 5554,for HLS - 8000. Clients must connect to Oja using these ports:
- rtmp://oja-addr:1935/< source-name >
- rtsp://oja-addr:5554/< source-name >
- http://oja-addr:8000/< source-name >
You can also change the value of any of these ports.
These settings are global: you cannot set any network address or port for only one source. The values of addresses and ports for a network connection apply to all sources at once
Please note that changes in this section will take effect only after server reboot.
You can set basic client protocol settings in this section. These parameters will be applied to each source that is created with a standard (basic) configuration.
You can set the basic configuration for each source type. Let's look at the parameters:
-> RTMP
| Parameter | Source type |
Description | Necessary | Possible values |
Default |
|---|---|---|---|---|---|
| Chunk size | Live and VoD |
A large message can be divided into chunks and sent in parts. For example, if we have one large 1Mb message, then the whole message will be quite slow to send, and may block the network connection for a certain time. If we split it into 4Kb chunks, we can easily mix it with chunks of other messages and send it without causing blocking. However, too small chunks can cause an increased load, as Oja will have to be constantly interrupted for sending to the network connection. |
yes | a number from 128 to 65535 | 4096 |
| Play | Live and VoD | Whether this source is allowed to play by protocol | yes | on, off | on |
| Publish | Live | Whether RTMP publishing to this source is allowed | yes | on, off | on |
| Interleave | Live and VoD | Whether data shuffling is allowed. If this parameter is enabled, then audio and video data will be transmitted in the same stream. | yes | on, off | off |
| Error Watermark | Live and VoD |
The maximum number of errors during the work of the source, after which it will be considered damaged, and all clients will be disconnected. This can happen when the network connection is unstable. If this parameter is not set, then the source will pay no attention to errors. |
no | a number from 1 to 100 | 10 |
| Priority Bitrate | VoD | In the case of a multi-bitrate container file, it is necessary to select the track with which bitrate will be broadcast on RTMP | yes | min, max | max |
| Chunk Duration | VoD |
When streaming VoD over RTMP, Oja sends data to the player in segments of N seconds. This parameter determines the duration of the segment that will be sent to the player via RTMP at one time If the segment duration is too long, then a significant consumption of RAM is possible, but at the same time, customers will be less likely to send requests to Oja for new segments. If the duration is too short, then the RAM will be used more economically. However, the load on the network will increase and performance may decrease, as Oja will access the hard drive more frequently and send data over the network connection. |
yes | duration from 1 second to 30 seconds | 10 seconds |
| Wait for key frame | Live | Is it necessary to wait for a keyframe before starting to send the stream to the connected player | yes | on, off | on |
-> RTSP
| Parameter | Source type |
Description | Necessary | Possible values |
Default |
|---|---|---|---|---|---|
| RTCP Timeout | Live and VoD | Rate in seconds at which the RTSP message will be sent | yes | A number from 1 to 10 | 5 |
| Play | Live and VoD | Whether this source is allowed to play by protocol | yes | on, off | on |
| Publish | Live | Whether RTSP publishing to this source is allowed | yes | on, off | on |
| Error Watermark | Live and VoD |
The maximum number of errors during the work of the source, after which it will be considered damaged, and all clients will be disconnected. This can happen when the network connection is unstable. If this parameter is not set, then the source will pay no attention to errors. |
no | A number from 1 to 10 | 10 |
| Wait for key frame | Live | Is it necessary to wait for a keyframe before starting to send the stream to the connected player | no | on, off | off |
-> HLS
| Parameter | Source type |
Description | Necessary | Possible values |
Default |
|---|---|---|---|---|---|
| Play | Live and VoD | Whether this source is allowed to play by HLS protocol | yes | on, off | on |
| Error Watermark | Live and VoD |
The maximum number of errors during the work of the source, after which it will be considered damaged, and all clients will be disconnected. This can happen when the network connection is unstable. If this parameter is not set, then the source will pay no attention to errors. |
no | a number from 1 to 100 | 10 |
| File cache size | Live |
Size in kilobytes of cache in RAM to send Live stream data. The data hits the cache, and then, when the cache is full, it is sent to disk in the desired segment. It improves performance because writing data to disk is a time consuming operation. On the other hand, a too large cache size with a large number of active sources can significantly consume RAM. |
yes | a number from 4 to 16384 | 1024 |
| Chunk Directory | Live | The path in the server file system where HLS segments will be saved as files | yes | Correct path to a directory that has read and write permissions | . (current directory) |
| Playlist Duration | Live | Duration in seconds of the playlist for the Livesource. A long playlist will allow clients to use Oja less often, but there will be a significant delay in playback time.A short playlist reduces the delay, but increases the load on the network. Also, the combination of low keyframe rates, short playlist, and long segments can cause errors. The reason is that the segments will not have time to record data and update according to key frames and at the same time will not exceed the duration of the playlist. | yes | duration from 10 seconds to 120 seconds | 30 seconds |
| Chunk Duration | Live and Vod |
Expected duration of one HLS segment. In the case of Live Source, this parameter determines the maximum duration of one file into which the stream is recorded. If the duration of the file is equal to or exceeds this value, then the segment is considered complete, the recording starts to a new file, the oldest segment is deleted, and the playlist is updated. This parameter determines how often clients will contact the server for new segments, and how often the playlist will be updated. In this case, the actual file size may be slightly less or more than the specified value, since it is calculated from the key frame rate in the stream. We recommend setting this parameter at least 3-4 times shorter than the playlist duration. As for the VoD source, a segment no longer than the specified duration will be read from the file, converted and sent to the client. If the segment duration is too long, then a significant consumption of RAM is possible, but at the same time clients will less often send requests to Oja for new segments. If the duration is too short, then the RAM will be used more economically, but the load on the network will increase and performance may decrease. This can happen because Oja will access the hard drive more often and send data over the network connection. |
yes | duration from 3 seconds to 30 seconds | 10 seconds |
You can define parameters for working with media files. These settings will be used while working with VoD sources
| Parameter | Container | Description | Necessary | Possible values |
Default |
|---|---|---|---|---|---|
| File wait timeout | all | File access timeout in milliseconds. If the timeout exceeds this value, the request to read the next segment will fail. If this option is not set, the client request will wait for access without a time limit. | no | duration from 10 milliseconds to 10000 milliseconds (10 seconds) | 1000 milliseconds (1 second) |
| Simultaneous access | all |
Maximum limit for simultaneous read access to a file. Each file read request increases the reader count; this counter decreases after the request is made. If the counter has become equal to the limit, then a new request to read the segment will wait until it is given access. If this parameter is not set, the operating system determines the maximum concurrent file access limit. |
no | a number from 1 (simultaneo us access is denied) to 65535 | Not set |
| Wait for bitrate | MKV | The MKV container does not have an average bitrate field. Some protocols require this value when clients connect. This parameter indicates how many milliseconds the file will be analyzed for average bitrate. | yes | duration from 10 milliseconds to 1000 milliseconds (1 second) | 100 milliseconds |
| Parse clusters | MKV |
Specifies in which case to analyze the 'cluster' element of the MKV file.
The analysis of the 'cluster' elements allows to read segments from the file faster, but it can take some time and require additional memory consumption. |
yes | yes, audio_only | audio_only |
| Parameter | Recording Container | Description | Necessary | Possible values |
Default |
|---|---|---|---|---|---|
| Path | all | The path in the server file system where recorded files will be saved | yes | Correct path to a directory that has read and write permissions | . (current directory) |
| Tracks Type | all | The type of stream tracks to be recorded | yes | audio, video, all | all |
| Immediately | all |
Is it necessary to start recording immediately after the start of the stream. If this option is disabled, then recording will need to be started manually from the source menu. |
yes | on, off | off |
| Error Watermark | all |
The maximum number of errors during the recorder operation, after which it will be considered damaged and the recording will be interrupted. If this parameter is not set, the recorder will ignore errors |
no | a number from 1 t | 10 |
| Max Duration | all |
The maximum duration of a single file. If the duration of the recorded file is equal to or larger than this value, a new file will be created in which recording will continue. If this parameter is not set, the recording will not switch to the new file due to the maximum duration being reached. |
no | Duration from 30 seconds or more | not set |
| Max File Size | all |
The maximum size of a single file. The maximum size of a single file. If the size of the recorded file is equal to or larger than this value, a new file will be created in which recording will continue If this parameter is not set, the recording will not switch to the new file due to the maximum size being reached. |
no | Size from 1 Mb and more | not set |
| Wait for keyframe | all | Is it necessary to wait for a keyframe before starting recording | yes | on, off | on |
| PSI Frequency | MPEGTS |
The frequency of generating PSI packets per second. If this parameter is not set, then PSI packets will be recorded only at the very beginning of the file |
no | a number from 1 to 10 | 1 |
| PCR Stream | MPEGTS | Is it necessary to transmit the PCR under a separate PID. | yes | on, off | on |
Oja can send multicast to the specified network address. The stream will send media packets using the specified protocol.
In this section, you can configure the parameters for sending multicast.
| Parameter | Protocol | Description | Necessary | Possible values |
Default |
|---|---|---|---|---|---|
| Enable | all | Whether multicast distribution is enabled by default. If enabled, then each new Live source will need to register the network address to which the multicast should be sent. | yes | on, off | off |
| Max Packet Size | all | The maximum size of a cached packet in bytes. If you need to send a large frame, for example, a key frame, then it will be split into packets of the specified size. | yes | a number from 64 to 8192 | 4096 |
| PSI Frequency | MPEGTS | The rate at which PSI packets are generated per second | yes | a number from 1 to 10 | 1 |