Streaming Music

Streaming Methods

Koel supports three streaming methods which can be configured via the STREAMING_METHOD setting in .env file:

• php: Uses native PHP file reading. This is the default method.
• x-accel-redirect: Only applicable if your webserver is nginx. Uses nginx's X-Accel module, designed for serving larger contents directly to the end user. Refer to nginx.conf.example for a sample nginx configuration file.
• x-sendfile: Only applicable if your webserver is Apache (with or without a proxy server like nginx). Uses Apache's mod_xsendfile module. You'll need to install and configure the module manually. A sample configuration is as following:

  LoadModule xsendfile_module   libexec/apache2/mod_xsendfile.so
  
  # These configuration can be put in the VirtualHost directive as well
  <IfModule mod_xsendfile.c>
    XSendFile on
    XSendFilePath /mnt/media
  </IfModule>

  Note that although its home page denotes "Apache2/Apache2.2," the module itself is known to work with later versions of Apache as well.

Tip

If you're using Koel mobile app and can't play the songs, try switching the streaming method to x-accel-redirect or x-sendfile instead of php.

Notice

Koel always uses the native PHP method if you're streaming from a cloud storage.

Transcoding

Koel can transcode your audio to cater to specific needs. To support transcoding, you'll need to have FFmpeg installed on your server and set its executable path via the FFMPEG_PATH setting in the .env file. The transcoding quality can also be controlled via OUTPUT_BIT_RATE (defaults to 128).

When transcoding is enabled, Koel caches the transcoded files to improve performance. If for any reason you want to clear the cache, run php artisan cache:clear.

Important

Transcoding is only supported for local storage. FTP and cloud storage drivers are not supported.

FLAC Transcoding

By default, Koel streams FLAC files as-is, which means the lossless audio quality is preserved. However, you can opt to have FLAC transcoded to mp3 to, for example, reduce bandwidth or support older devices. This behavior can be controlled via the TRANSCODE_FLAC setting in .env file:

• false: Disable transcoding and stream FLAC files as-is, producing the lossless audio quality. This is the default behavior.
• true: Transcode FLAC to mp3 before streaming.

Forced Transcoding

For audio formats that aren't widely supported by browsers, such as AIFF, Koel will always resort to transcoding. If you upload files in such formats, make sure the FFmpeg setup and configuration (see above) are correct.

Transcoding on Mobile

On a mobile device where data usage is a concern, the user might want to instruct Koel to transcode all songs to a lower bitrate to save bandwidth. This can be done via the Preferences screen.