Contents
Installation
Installing ACE Stream on Debian/Ubuntu from repository
Step 1
Add link on appropriate repository into /etc/apt/sources.list file.
Repository should be selected according to operating system.
Debian 6+:
deb http://repo.acestream.org/debian/ squeeze main or deb http://repo.acestream.org/debian/ sid main
Note: packages in sid repository are assembled with dependencies that correspond to official sid-repositories of Debian. If you don't know, which repository to choose, use squeeze.
Ubuntu 11.10:
deb http://repo.acestream.org/ubuntu/ oneiric main
Ubuntu 12.04:
deb http://repo.acestream.org/ubuntu/ precise main
Ubuntu 12.10:
deb http://repo.acestream.org/ubuntu/ quantal main
Step 2
Installing public key. To do this you have to run the following command:
Debian:
wget -O - http://repo.acestream.org/keys/acestream.public.key | apt-key add -
Ubuntu:
sudo wget -O - http://repo.acestream.org/keys/acestream.public.key | sudo apt-key add -
Step 3
Installing the right package. For example, for engine installation you have to install acestream-engine package.
Debian
apt-get update apt-get install acestream-engine
Ubuntu
sudo apt-get update sudo apt-get install acestream-engine
The following packages are available in the repository for Ubuntu:
- acestream-engine - engine
- acestream-mozilla-plugin - plug-in for browser
- acestream-player - desktop player
- acestream-player-data - set of common libraries for the player and plug-in
- acestream-full - full package, including all of the above
For Debian only the engine (acestream-engine) is available.
Installing ACE Stream package on Ubuntu from deb-package
You can install ACE Stream on Ubuntu without using repository. To do this you need to download the installation package by one of links below and install it using a package manager (for example, by double click on downloaded package).
Package for 32-bit versions of Ubuntu:
http://dl.torrentstream.org/products/acestream-full/ubuntu/i368/latest
Package for 64-bit versions of Ubuntu:
http://dl.torrentstream.org/products/acestream-full/ubuntu/amd64/latest
Supported versions of Ubuntu: 11.10, 12.04, 12.10
This intallation package is an analog of acestream-full package from repository. It includes the engine, player and plug-in for browsers.
Launching broadcast
Main terms
- Source - a program that accepts broadcast's HTTP-stream and provides playback of broadcast using ACE Stream software.
- Support node - a program allowing to scale broadcast using additional server equipment and Internet-channels.
- Client - ACE Stream software, which is used to play broadcast.
Common work scheme
Broadcast organization starts from launching the source (command acestreamengine-stream). The source accepts HTTP-stream to input (at this moment HTTP-streams with MPEG-TS encapsulation are supported) with original broadcast and creates a file with acelive extension after the launch. This file is a unique identifier of broadcast and it is used for connection and playback by clients.
Syntax of acestreamengine-stream command
acestreamengine-stream command launches broadcast source.
required parameters
- --name NAME - broadcast name (this name is used when creating acelive and other service files)
- --source SOURCE - source (link to http-stream)
- --bitrate BITRATE - average bitrate of stream in bytes per second
optional parameters
- --title TITLE - "readable" broadcast name (this name is shown to clients). If it's not specified, it's taken from --name
- --destdir DESTDIR - old parameter, it's better to use --cache-dir and --publish-dir
- --cache-dir CACHE_DIR - directory for creating service files (broadcast cache and others)
- --publish-dir PUBLISH_DIR - directory, in which acelive-file will be created
- --piecesize PIECESIZE - piece size in bytes (if it's not specified, it's set automatically depending on bitrate)
- --duration DURATION - size of broadcast cache in format HH:MM:SS (by default, one hour: 01:00:00)
- --host HOST - set address of local tracker manually
- --port PORT - port, where the engine works
- --skip-internal-tracker - disable local tracker
- --add-authorized-peers - add list of authorized peers to acelive file
- --private-source - make the source private
- --support-node SUPPORT_NODE - add support node (in format ip:port). This parameter may appear multiple times if several support nodes have to be added.
- --tracker TRACKER - add tracker(announce url). This parameter may appear multiple times.
- --trackers TRACKERS - old format for adding trackers (announce url list separated by commas)
- --provider-key PROVIDER_KEY - provider's key (only for commercial broadcasts)
- --maxclients MAXCLIENTS - maximum number of peers, on which data from the source are given simultaneously
- --show-pieces - show in log numbers of pieces as they are created
- --show-peers - periodically show in log list of connected peers
- --debug DEBUG - set debug level
additional
- -h, --help - show commands' description
Syntax of acestreamengine-node command
acestreamengine-node command launches support node.
required parameters
- --url URL> - link to acelive file of broadcast
optional parameters
- --port PORT - port(by default: 8621)
- --state-dir STATE_DIR - directory for temporary files (it's deleted after support node installation)
- --source-node SOURCE_NODE - address of broadcast source (ip:port)
- --support-node SUPPORT_NODE - add address of another support node (ip:port). This parameter may appear multiple times.
- --allow-source-download - allow receiving data from the source
- --allow-support-download - allow receiving data from other support nodes
- --allow-peers-download - allow receiving data from ordinary peers
- --max-incoming-connects MAX_INCOMING_CONNECTS - maximum number of incoming connections (from other peers) (by default: 1000)
- --max-outgoing-connects MAX_OUTGOING_CONNECTS - maximum number of outgoing connections (to other peers) (by default: 50)
- --max-upload-slots MAX_UPLOAD_SLOTS - maximum number of peers, on which data from support node are given simultaneously (by default: 7)
- --max-download-speed MAX_DOWNLOAD_SPEED - maximum download speed (byte/s). By default: 0 (no restrictions).
- --max-upload-speed MAX_UPLOAD_SPEED - maximum upload speed (byte/s). By default: 0 (no restrictions).
- --show-pieces -show in log numbers of pieces as they are created
- --show-peers - periodically show in log list of connected peers
- --stats-report-interval STATS_REPORT_INTERVAL - set interval in seconds to show in log information about download/upload speep. By default: 0 (do not show).
- --debug DEBUG - set debug level
additional
- -h, --help - show commands' description
Embedded tracker
Embedded tracker is a tracker embedded into broadcast source. If it's not disabled by --skip-internal-tracker option, its address will be added to acelive-file automatically.
When organizing broadcast with many users, we recommend to disable embedded tracker and replace it with external tracker with a good productivity (for example, XBT Tracker).
Authorized nodes
Client have to establish connection with at least two other nodes or an authorized node, to be connected to broadcast and start playback. Authorized node is a node, which was marked by broadcast's creator as a "trustworthy". Usually it's a broadcast source and/or support nodes.
The latest versions of ACE Stream software support using list of authorized nodes in acelive-file. For this --add-authorized-peers option is set when creating broadcast, after this the list of authorized nodes is created and added to acelive-file. Broadcast source (if it's not private) and all specified support nodes are in the list of authorized nodes. Clients that received this acelive-file use the list to determine whether a node is authorized.
If the list of authorized nodes was not added to acelive-file or an old version of ACE Stream, which doesn't understand this list, is installed, then authorized node is a node, IP address of which matches address of the first tracker from trackers' list. If embedded tracker is enabled on the source, it will be the first one on the list and clients will consider the source as authorized node. If embedded tracker is disabled, to support other clients we recommend to put on the first place tracker, located on the same server as broadcast source (so addresses of the first tracker and the source matched) or use at least one support node (so clients, when starting broadcast, could connect to two peers simultaneously, even if nobody watches broadcast).
Examples
For examples let's assume that there is a local network with three servers:
- 192.168.1.1 - server for the source
- 192.168.1.2 - server for support node
- 192.168.1.3 - server for support node
- 192.168.1.100 - server that gives original broadcast's stream (HTTP MPEG-TS) at http://192.168.1.100/stream (average bitrate of stream - 300 000 byte/s)
It's assumed that on server 192.168.1.1 there is a web-server with a core directory /home/www and two other directories:
- /home/www/streams - for keeping acelive-files, which will be available for downloading by a link like http://192.168.1.1/streams/test.acelive
- /tmp/streams - for keeping cache and service files of broadcast
Source with embedded tracker
This is the easiest way to launch broadcast that does not require launching support nodes and installing additional trackers. This method is suitable for broadcasts with a small number of users.
We launch the source on server 192.168.1.1:
acestreamengine-stream \ --name "test" \ --title "Test broadcast" \ --source "http://192.168.1.100/stream" \ --bitrate 300000 \ --publish-dir "/home/www/streams" \ --cache-dir "/tmp/streams" \ --add-authorized-peers \ > /tmp/test-source.log 2>&1
The last line is used to write logs into file /tmp/test-source.log. acestreamengine-stream shows all debug information in console in STDERR.
--add-authorized-peers option adds the list of authorized nodes to acelive-file (in this case, it's the source: 192.168.1.1).
After broadcast's launch a file test.acelive will be created in directory /home/www/streams, in directory /tmp/streams such files will be created:
- test - broadcast cache. This file's size is approximately equal to stream_duration_in_seconds (--duration option, by default: 1 hour) * bitrate byte
- test.restart - information for correct restart of broadcast is kept here
- test.sauth - key for a broadcast's digital signature
To watch broadcasts clients can download broadcast file at http://192.168.1.1/streams/test.acelive and start it in ACE Stream player or use other ways (Ways to watch broadcasts).
Source with external tracker
If broadcast involves a large number of users, it's better to use external tracker and disable embedded one (to reduce burden on the source).
We recommed to use XBT Tracker as external tracker.
In this example we assume that XBT Tracker is installed and launched on server 192.168.1.1. Now broadcast's launch will look like:
acestreamengine-stream \ --name "test" \ --title "Test broadcast" \ --source "http://192.168.1.100/stream" \ --bitrate 300000 \ --publish-dir "/home/www/streams" \ --cache-dir "/tmp/streams" \ --add-authorized-peers \ --skip-internal-tracker \ --tracker "udp://192.168.1.1:2710/announce" \ > /tmp/test-source.log 2>&1
--skip-internal-tracker option disconnects embedded tracker, --tracker option connects external tracker.
Source with two support nodes
If there is not enough upstream bandwidth for normal work of broadcast on the source, support nodes can be used. Support node is often a node that receives data from the source and gives to clients (though support node can also receive data from other support nodes and even clients, depending on its settings). It makes sense to install support node on a separate server with a good width of output channel.
To make a scheme with support nodes work with maximum efficiency, addresses of these nodes must be given to the source using --support-node option:
--support-node: acestreamengine-stream \ --name "test" \ --title "Test broadcast" \ --source "http://192.168.1.100/stream" \ --bitrate 300000 \ --port 7764 \ --publish-dir "/home/www/streams" \ --cache-dir "/tmp/streams" \ --add-authorized-peers \ --skip-internal-tracker \ --tracker "udp://192.168.1.1:2710/announce" \ --support-node "192.168.1.2:8621" \ --support-node "192.168.1.3:8621" \ > /tmp/test-source.log 2>&1
Launch support nodes on servers 192.168.1.2 and 192.168.1.3 (commands are the same):
acestreamengine-node \ --url "http://192.168.1.1/streams/test.acelive" \ --state-dir "/tmp" \ --source-node "192.168.1.1:7764" \ --allow-source-download \ > /tmp/test-node.log 2>&1
Option --source-node sets source address.
Option --allow-source-download allows support node to download data from the source (downloading from other support nodes and clients in this case is forbidden).
To allow support nodes to download data from other suppport nodes, you should set a list of other nodes using --support-node option and allow downloading using --allow-support-download option.
On server 192.168.1.2 it will look like:
acestreamengine-node \ --url "http://192.168.1.1/streams/test.acelive" \ --state-dir "/tmp" \ --source-node "192.168.1.1:7764" \ --allow-source-download \ --support-node "192.168.1.3:8621" \ --allow-support-download \ > /tmp/test-node.log 2>&1
On server 192.168.1.3:
acestreamengine-node \ --url "http://192.168.1.1/streams/test.acelive" \ --state-dir "/tmp" \ --source-node "192.168.1.1:7764" \ --allow-source-download \ --support-node "192.168.1.2:8621" \ --allow-support-download \ > /tmp/test-node.log 2>&1
Private source with two support nodes
Sometimes it may be necessary to prevent clients from direct access to broadcast source. For example, the source may be located on server in protected area without access from the outer world. In this case broadcast can be organized by the following scheme:
- the source is made private (only support nodes, specified explicitly, can receive data from it)
- support nodes receive data from the source and give to clients
- clients receive data from support nodes
To make the source private, option --private-source must be specified:
acestreamengine-stream \ --name "test" \ --title "Test broadcast" \ --source "http://192.168.1.100/stream" \ --bitrate 300000 \ --port 7764 \ --publish-dir "/home/www/streams" \ --cache-dir "/tmp/streams" \ --add-authorized-peers \ --skip-internal-tracker \ --tracker "udp://192.168.1.2:2710/announce" \ --support-node "192.168.1.2:8621" \ --support-node "192.168.1.3:8621" \ --private-source \ > /tmp/test-source.log 2>&1
Notice that in this configuration tracker's address is changed to udp://192.168.1.2:2710/announce. It was made to support old versions of clients, which do not process a list of authorized peers (more details here Authorized peers).
Launch support nodes on servers 192.168.1.2 and 192.168.1.3 as usual:
acestreamengine-node \ --url "http://192.168.1.1/streams/test.acelive" \ --state-dir "/tmp" \ --source-node "192.168.1.1:7764" \ --allow-source-download \ > /tmp/test-node.log 2>&1