Mopidy has a lot of config values you can tweak, but you only need to change a
few to get up and running. A complete
be as simple as this:
[mpd] hostname = :: [spotify] username = alice password = mysecret
Mopidy primarily reads config from the file
~ means your home directory.
If your username is
alice and you are running Linux, the config file should
probably be at
/home/alice/.config/mopidy/mopidy.conf. You can either
create the configuration file yourself, or run the
mopidy command, and it
will create an empty config file for you and print what config values must be
set to successfully start Mopidy.
When you have created the configuration file, open it in a text editor, and add the config values you want to change. If you want to keep the default for a config value, you should not add it to the config file, but leave it out so that when we change the default value in a future version, you won’t have to change your configuration accordingly.
To see what’s the effective configuration for your Mopidy installation, you can run:
This will print your full effective config with passwords masked out so that you safely can share the output with others for debugging.
You can find a description of all config values belonging to Mopidy’s core below, together with their default values. In addition, all extensions got additional config values. The extension’s config values and config defaults are documented on the extension pages.
Default core configuration¶
[logging] color = true console_format = %(levelname)-8s %(message)s debug_format = %(levelname)-8s %(asctime)s [%(process)d:%(threadName)s] %(name)s\n %(message)s debug_file = mopidy.log config_file = [audio] mixer = software mixer_volume = output = autoaudiosink visualizer = [proxy] scheme = hostname = port = username = password =
Core configuration values¶
Mopidy’s core has the following configuration values that you can change.
Audio mixer to use.
The default is
software, which does volume control inside Mopidy before the audio is sent to the audio output. This mixer does not affect the volume of any other audio playback on the system. It is the only mixer that will affect the audio volume if you’re streaming the audio from Mopidy through Shoutcast.
If you want to use a hardware mixer, you need to install a Mopidy extension which integrates with your sound subsystem. E.g. for ALSA, install Mopidy-ALSAMixer.
Initial volume for the audio mixer.
Expects an integer between 0 and 100.
Setting the config value to blank leaves the audio mixer volume unchanged. For the software mixer blank means 100.
Audio output to use.
Expects a GStreamer sink. Typical values are
shout2send, and additional arguments specific to each sink. You can use the command
gst-inspect-0.10to see what output properties can be set on the sink. For example:
Whether or not to colorize the console log based on log level. Defaults to
The log format used for informational logging.
See the Python logging docs for details on the format.
The log format used for debug logging.
See the Python logging docs for details on the format.
The file to dump debug log data to when Mopidy is run with the
Config file that overrides all logging config values, see the Python logging docs for details.
loglevelsconfig section can be used to change the log level for specific parts of Mopidy during development or debugging. Each key in the config section should match the name of a logger. The value is the log level to use for that logger, one of
Not all parts of Mopidy or all Mopidy extensions respect the proxy server configuration when connecting to the Internt. Currently, this is at least used when Mopidy’s audio subsystem reads media directly from the network, like when listening to Internet radio streams, and by the Mopidy-Spotify extension. With time, we hope that more of the Mopidy ecosystem will respect these configurations to help users on locked down networks.
URI scheme for the proxy server. Typically
Hostname of the proxy server.
Port number of the proxy server.
Username for the proxy server, if needed.
Password for the proxy server, if needed.
Mopidy’s extensions have their own config values that you may want to tweak. For the available config values, please refer to the docs for each extension. Most, if not all, can be found at Extensions.
Mopidy extensions are enabled by default when they are installed. If you want
to disable an extension without uninstalling it, all extensions support the
enabled config value even if it isn’t explicitly documented by all
extensions. If the
enabled config value is set to
false the extension
will not be started. For example, to disable the Spotify extension, add the
following to your
[spotify] enabled = false
Custom audio sink¶
If you have successfully installed GStreamer, and then run the
gst-inspect-0.10 command, you should see a long listing of installed
plugins, ending in a summary line:
$ gst-inspect-0.10 ... long list of installed plugins ... Total count: 254 plugins (1 blacklist entry not shown), 1156 features
Next, you should be able to produce a audible tone by running:
gst-launch-0.10 audiotestsrc ! audioresample ! autoaudiosink
If you cannot hear any sound when running this command, you won’t hear any
sound from Mopidy either, as Mopidy by default uses GStreamer’s
autoaudiosink to play audio. Thus, make this work before you file a bug
If you for some reason want to use some other GStreamer audio sink than
autoaudiosink, you can set the
audio/output config value to a
partial GStreamer pipeline description describing the GStreamer sink you want
mopidy.conf for using OSS4:
[audio] output = oss4sink
Again, this is the equivalent of the following
gst-inspect command, so make
this work first:
gst-launch-0.10 audiotestsrc ! audioresample ! oss4sink
Streaming through SHOUTcast/Icecast¶
Currently, Mopidy does not handle end-of-track vs end-of-stream signalling in GStreamer correctly. This causes the SHOUTcast stream to be disconnected at the end of each track, rendering it quite useless. For further details, see #492. You can also try the workaround mentioned below.
If you want to play the audio on another computer than the one running Mopidy, you can stream the audio from Mopidy through an SHOUTcast or Icecast audio streaming server. Multiple media players can then be connected to the streaming server simultaneously. To use the SHOUTcast output, do the following:
Install, configure and start the Icecast server. It can be found in the
icecast2package in Debian/Ubuntu.
audio/outputconfig value to
lame ! shout2send. An Ogg Vorbis encoder could be used instead of the lame MP3 encoder.
You might also need to change the
shout2senddefault settings, run
gst-inspect-0.10 shout2sendto see the available settings. Most likely you want to change
Example for MP3 streaming:
[audio] output = lame ! shout2send mount=mopidy ip=127.0.0.1 port=8000 password=hackme
Example for Ogg Vorbis streaming:
[audio] output = audioresample ! audioconvert ! vorbisenc ! oggmux ! shout2send mount=mopidy ip=127.0.0.1 port=8000 password=hackme
Other advanced setups are also possible for outputs. Basically, anything you
can use with the
gst-launch-0.10 command can be plugged into
Workaround for end-of-track issues - fallback streams
By using a fallback stream playing silence, you can somewhat mitigate the signalling issues.
Example Icecast configuration:
<mount> <mount-name>/mopidy</mount-name> <fallback-mount>/silence.mp3</fallback-mount> <fallback-override>1</fallback-override> </mount>
silence.mp3 file needs to be placed in the directory defined by
New configuration values¶
Mopidy’s config validator will stop you from defining any config values in your config file that Mopidy doesn’t know about. This may sound obnoxious, but it helps us detect typos in your config, and deprecated config values that should be removed or updated.
If you’re extending Mopidy, and want to use Mopidy’s configuration system, you can add new sections to the config without triggering the config validator. We recommend that you choose a good and unique name for the config section so that multiple extensions to Mopidy can be used at the same time without any danger of naming collisions.