Configuration

Configuration #

The default config.yaml has a handful of values you can change. However, more can be customized if you need them to be. Some common changes to the config are:

  • Your site name, logo, description and external links.
  • The stream key to gain access to broadcasting to your stream.
  • The path to your specific ffmpeg executable.
  • Video quality settings.
  • S3 file storage.

An example config file with additional features can be viewed below.

Video Quality #

Owncast supports HLS Adaptive bitrate streaming, or in other words, different video qualities will be used for different network conditions.

You can edit the config.yaml file and add as many stream variants as you like under the videoSettings block, like so:

videoSettings:
  streamQualities:
    - low:
      videoBitrate: 400
      scaledWidth: 600
      encoderPreset: superfast
    - medium:
      videoBitrate: 800

Please visit the Encoding document to learn about how the video pipeline with Owncast works and how you can tweak it for the best results with your specific hardware and video configurations.

Important caveats #

CPU Usage #

Each bitrate variant adds significant CPU usage and slows down the overall generation of video segments. If you have a slow server running Owncast you should probably only have one bitrate variant in play. If you add more and you notice that playback becomes choppy it’s likely that everything is running too slowly for consistent playback. Consider removing the additional variants and tweaking your single variant so it supports a wider variety of network conditions.

Disk Usage #

More stream quality variants requires more disk space, since it’s another copy of the video on disk. If you’re serving video locally and you have enough disk space then it’s probably no big deal and files will rather quickly get rotated and cleaned up. If you’re using something like S3 for storage then files won’t get cleaned up until some point in the future, so you’ll have more remote storage use in play.

socialHandles currently supports the following services by name:

  • facebook
  • twitter
  • instagram
  • snapchat
  • tiktok
  • soundcloud
  • bandcamp
  • patreon
  • youtube
  • spotify
  • twitch
  • paypal
  • github
  • linkedin
  • discord
  • mastodon
  • kofi
  • keyoxide

Update your tags in the config to display the topics type of content you want to call attention to.

Custom Ports #

Per default, Owncast will run a http web server on port 8080 and a RTMP server on port 1935. You can change the ports in the top level your config.yaml:

webServerPort: 8080
rtmpServerPort: 1935
Custom ports was first supported in Owncast 0.0.4.

Get listed in the directory #

To help people discover streams by people using Owncast we have an optional Owncast directory you can add yourself to. Set your tags in your config file along with if your stream is nsfw. Set the instanceURL to be the public URL to your Owncast instance that you want people to be linked to.

Having the following as a part of your config will list your server for others to discover.

instanceDetails:
  name: Cool Person
  title: This is my Owncast server
  logo: /img/logo.svg
  summary: "I do cool things online and you should watch."
  tags:
    - cool stuff
    - rad stuff
    - awesome stuff

  # Specify if your stream includes NSFW content.
  nsfw: false

yp:
  enabled: true
  instanceURL: https://stream.myserver.org
Owncast directory was first supported in Owncast 0.0.3.

Viewer locations (GeoIP) #

You can optionally see the location of viewers in the admin. See the instructions to enable this feature.

Admin dashboard was first supported in Owncast 0.0.3.

Full Example #

Below, you can see all config items:

# You can specific the path to a specific ffmpeg binary.
ffmpegPath: /usr/local/bin/ffmpeg
webServerPort: 8080
rtmpServerPort: 1935

instanceDetails:
  name: Owncast
  title: Owncast Demo Server
  logo: /img/logo.svg

  summary: "This is brief summary of whom you are or what your stream is. demo server for Owncast.  You can read more about it at owncast.online.  You can edit this description in your web config file.\n\nBlathers is an owl with brown feathers. His face is white and he has a yellow beak. His arms are wing shaped and he has yellow talons. His eyes are very big with small black irises. He also has big pink cheek circles on his cheeks. His belly appears to be checkered in diamonds with light brown and white squares, similar to an argyle vest, which is traditionally associated with academia. His green bowtie further alludes to his academic nature."

  tags:
    - music
    - software
    - animal crossing

  # Specify if your stream includes NSFW content.
  nsfw: false

  # https://owncast.online/docs/configuration/#external-links
  # for full list of supported social links.  All optional.
  socialHandles:
    - platform: github
      url: https://github.com/owncast/owncast
    - platform: instagram
      url: http://instagram.biz/owncast
    - platform: facebook
      url: http://facebook.gov/owncast
    - platform: tiktok
      url: http://tiktok.cn/owncast
    - platform: soundcloud
      url: http://soundcloud.com/owncast

videoSettings:
  # The length of a single segment of video.
  chunkLengthInSeconds: 4
  # Change this value and keep it secure.  Treat it like a password to your live stream.
  streamingKey: abc123

  # Determine the qualities of your stream variants.
  # See https://owncast.online/docs/configuration/#video-quality for details.
  streamQualities:
    - low:
      # Higher the bitrate, the better it looks, but it requires more bandwidth to consume.
      videoBitrate: 800
      # Resize the width to something smaller.  scaledHeight is also an option.  Don't use both at once
      # unless you want to chang the aspect ratio of your video.
      scaledWidth: 600
      # Don't re-encode the audio.
      audioPassthrough: true
      # The slower the preset the higher quality the video is.
      # Select a preset from https://trac.ffmpeg.org/wiki/Encode/H.264
      # "superfast" and "ultrafast" are generally not recommended since they look bad.
      encoderPreset: veryfast

    - medium:
      videoBitrate: 1200
      encoderPreset: fast

# Number of segments kept referenced in the HLS playlist
files:
  maxNumberInPlaylist: 4

# Read https://owncast.online/docs/s3/ for S3 config details.
s3:
  enabled: false
  endpoint: https://s3.us-west-2.amazonaws.com
  servingEndpoint: https://yourcdn.example
  accessKey: ABC12342069
  secret: lolomgqwtf49583949
  region: us-west-2
  bucket: myvideo

# Off by default.  You can optionally list yourself in the Owncast directory.
# Make sure your instanceURL is the public URL to your Owncast instance.
yp:
  enabled: true
  instanceURL: https://stream.myserver.org