Funkwhale
/
Clementine-audio-player-Mac-Linux-Windows
mirror of https://github.com/clementine-player/Clementine
1
0
Fork 0
Code Issues Releases Wiki Activity

Add Wiki pages from Google Code

David Sansome 2013-12-01 19:33:43 +11:00
parent 96be2b7868
commit d54a540e01
18 changed files with 1321 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
Compiling-from-Source-Mac.md Normal file

@ -0,0 +1,83 @@
# Instructions for compiling Clementine from source on Mac and creating a deployable disk image (dmg).
## Introduction
The method described here uses fink for any tools that aren't directly related to the final clementine binary (such as cmake, libtool, stow, etc.) Most other dependencies live in Clementine git and are compiled from source.
## Required frameworks
Download and install these frameworks:
- [Growl framework](http://growl.info/downloads#devdownloads)
- [Sparkle framework](http://sparkle.andymatuschak.org/)
## Xcode
Download and install the latest version of Xcode from the app store. Once Xcode is installed, open it, go to the Preferences dialog, click the Downloads tab and install the "Command Line Tools" component.
## Fink setup (for OS X <= 10.6)
Fink should be configured to use the unstable repository and to build 64-bit packages.
If you haven't used fink before:
- [Download, bootstrap, and update fink](http://www.finkproject.org/download/srcdist.php).
- Run `fink configure` and choose answer "y" to enable the unstable tree.
- Run `fink selfupdate`
Then to install all the dependencies:
fink install cmake stow autoconf automake1.11 gcc4.2 gettext gettext-tools make pkgconfig unzip libtool14 libtool14-shlibs
Be careful not to install any other dependencies from fink. If any of the packages that get compiled below are installed with fink **you must remove them or Clementine may link to the wrong versions**.
## Homebrew setup (for OS X 10.7+)
If you haven't used homebrew before:
- [Follow the instructions](https://github.com/mxcl/homebrew/wiki/installation).
brew install cmake gettext intltool pkg-config stow wget autoconf
## Compiling dependencies
I've gathered up all the source packages that are required for Clementine, and put them in the git repository. You can [browse them here](http://code.google.com/p/clementine-player/source/list?repo=dependencies). We're going to check them out into `/src`, and compile each package into `/target`.
You can do all this as root, or as a normal user if you chown -R /src and /target.
mkdir -p /src /target/stow
git clone https://code.google.com/p/clementine-player.dependencies/ /src
Now you're ready to start compiling:
cd /src/macosx
make
This will take some time - anywhere from 20 minutes to an hour depending on how many processors you have. Each package will get compiled with -j2, you can change that by editing the Makefile. You can compile *different packages* in parallel by passing -j when you call make, but I sometimes get the dependencies wrong so it might not always work.
## Clementine
- Compile Clementine:
mkdir bin
cd bin
PKG_CONFIG_PATH=/target/lib/pkgconfig:/usr/local/Library/Homebrew/pkgconfig cmake .. \
-DCMAKE_OSX_ARCHITECTURES=x86_64 \
-DBOOST_ROOT=/target \
-DPROTOBUF_LIBRARY=/target/lib/libprotobuf.dylib \
-DPROTOBUF_INCLUDE_DIR=/target/include/ \
-DPROTOBUF_PROTOC_EXECUTABLE=/target/bin/protoc \
-DSPOTIFY=/target/libspotify.framework \
-DGLEW_INCLUDE_DIRS=/target/include \
-DGLEW_LIBRARIES=/target/lib/libGLEW.dylib \
-DLASTFM_INCLUDE_DIRS=/target/include/ \
-DLASTFM_LIBRARIES=/target/lib/liblastfm.dylib \
-DFFTW3_DIR=/target \
-DCMAKE_INCLUDE_PATH=/target/include \
-DQT_QMAKE_EXECUTABLE=/target/bin/qmake
make
- Copy icon file and resources
make install
- Generate a disk image:
make dmg

111
Compiling-from-Source-Windows.md Normal file

@ -0,0 +1,111 @@
# Instructions for compiling Clementine from source on Windows
## Overview
The method described here uses MinGW to cross-compile from an Ubuntu host system.
## Making a chroot
It's perfectly fine to compile Clementine on a real Ubuntu system, but you will end up installing files all over your system so it might be preferable to set up a *chroot* first. Full instructions can be found on the [DebootstrapChroot](https://wiki.ubuntu.com/DebootstrapChroot) page on the Ubuntu wiki, but here's an outline:
sudo apt-get install debootstrap schroot
sudo debootstrap --variant=buildd --arch i386 precise /var/chroot/mingw http://archive.ubuntu.com/ubuntu/
sudo cp /etc/{passwd,shadow,group,sudoers} /var/chroot/mingw/etc/
sudo sh -c "echo /proc /var/chroot/mingw/proc none rbind 0 0 >> /etc/fstab"
sudo sh -c "echo mingw > /var/chroot/mingw/etc/debian_chroot"
sudo mount /var/chroot/mingw/proc
Edit `/var/chroot/mingw/etc/apt/sources.list` and add the "`universe restricted multiverse`" repositories.
Now edit `/etc/schroot/schroot.conf` and add the following section at the bottom:
[mingw]
description=MinGW build environment
directory=/var/chroot/mingw
groups=chroot
personality=linux32
You can now log into your chroot by running `schroot -c mingw`. Follow the rest of this guide inside the chroot.
## Installing the build tools
apt-get update
apt-get install yasm cmake qt4-dev-tools stow unzip autoconf libtool \
bison flex pkg-config gettext libglib2.0-dev intltool wine git-core \
sudo
Install natty's version of libtool from http://old-releases.ubuntu.com/ubuntu/pool/main/libt/libtool/ (get version 2.2.6b)
## Installing the compiler
We use mingw-w64 to compile Clementine. Download the latest version from http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Automated%20Builds/
Extract it inside the chroot to the **/mingw** directory, and make then put it on your `$PATH`:
cd /
mkdir mingw
cd mingw
tar -xvf mingw-w32-bin_i686-linux_20121015.tar.bz2
chmod +rx /root
export PATH=$PATH:/mingw/bin
## Setting up wine
You have to do this each time you restart if you're using a chroot, it registers .exe files as being executable:
mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc
echo ':DOSWin:M::MZ::/usr/bin/wine:' > /proc/sys/fs/binfmt_misc/register
## Compiling dependencies
I've gathered up all the source packages that are required for Clementine, and put them in the svn repository. You can [browse them here](http://code.google.com/p/clementine-player/source/browse/?repo=dependencies). We're going to check them out into `/src`, and compile each package into `/target` (which is a symlink to `/usr/i586-mingw32msvc`).
You can do all this as root, or as a normal user if you chown -R /src and /target.
If `/usr/i586-mingw32msvc` doesn't exists, just create it.
mkdir /usr/i586-mingw32msvc
ln -s /usr/i586-mingw32msvc /target
mkdir /src /target/stow /target/bin
ln -s /mingw/i686-w64-mingw32/lib/libgcc_s_sjlj-1.dll /target/bin/
git clone https://code.google.com/p/clementine-player.dependencies/ /src
Now you're ready to start compiling:
cd /src/windows
make
This will take some time - anywhere from 20 minutes to an hour depending on how many processors you have. Each package will get compiled with -j8, you can change that by editing the Makefile. You can compile *different packages* in parallel by passing -j when you call make, but I sometimes get the dependencies wrong so it might not always work.
When it's done there will be a `/src/windows/clementine-deps` folder with all the .dlls that get bundled with Clementine.
## Compiling Clementine
Now that we've got all the dependencies this is quite simple:
git clone https://code.google.com/p/clementine-player/ clementine-player
mkdir clementine-player/bin
cd clementine-player/bin
PKG_CONFIG_LIBDIR=/target/lib/pkgconfig \
cmake .. \
-DCMAKE_TOOLCHAIN_FILE=/src/Toolchain-mingw32.cmake \
-DQT_HEADERS_DIR=/target/include \
-DQT_LIBRARY_DIR=/target/bin \
-DPROTOBUF_PROTOC_EXECUTABLE=/target/bin/protoc
make
If you're lucky there should be a `bin/clementine.exe`
## Making the installer
Creating the windows installer requires nsis:
sudo apt-get install nsis
cd clementine-player/dist/windows
ln -s /src/windows/clementine-deps/* .
ln -s ../../bin/clementine*.exe .
makensis clementine.nsi

101
Cue-Sheet-Support.md Normal file

@ -0,0 +1,101 @@
# CUE sheet support description
<wiki:toc max_depth="1" />
# Introduction
If you don't know what CUE is, you probably don't need to read this. Still, if you'd like to learn what CUE is, a good starting point would be this Wikipedia's article: [http://en.wikipedia.org/wiki/Cue_sheet_(computing)]. Before we start, check out CUEs in action!
----
A media file and it's CUE sheet:
http://student.agh.edu.pl/~bara/cue.png
Dragging the CUE over Clementine:
http://student.agh.edu.pl/~bara/cue_dnd.png
Notice that both songs that were described in the sheet appear in the playlist even though there is only one media file:
http://student.agh.edu.pl/~bara/cue_result.png
# Dictionary
**CUE related song** - every song represented by a media file described with a CUE sheet. For example, song1.wav is CUE related:
C:\songs\best\song1.wav
C:\media.cue:
FILE C:\songs\best\song1.wav WAVE
PERFORMER "Artist"
TITLE "Album"
TRACK 01 AUDIO
TITLE "Title"
INDEX 00 00:00:00
INDEX 01 00:01:00
**CUE associated song** - song for which an associated .cue exists. By associated .cue we mean a file with this path = _DIR/FILE_NAME.cue_ for a media file with this path = _DIR/FILE_NAME.MEDIA_EXTENSION_. For example, those two files are associated:
~/MUSIC/A_DJ/A_Mix/a_mix.mp3
~/MUSIC/A_DJ/A_Mix/a_mix.cue
# CUE sheets outside the library
When we're dealing with CUE sheets outside of the library, we're talking about the full spectrum of features. When loading CUE related songs using the 'Files' tab or dragging and dropping such songs from your native file browser:
- all metadata from sheet (CUE tags like TITLE, PERFORMER, SONGWRITER etc.) is used
- Clementine will try to extract as much data from the CUE as it's possible, ignoring the uncritical CUE errors in the process
- multiple FILE based CUEs are supported
- both relative and absolute FILE paths are supported
You can open any .cue file this way and Clementine will try to find the related media files and load them using both absolute and relative paths.
Also, when you're opening a media file, if Clementine finds an associated CUE, it will use it to split the media file to sections if necessary.
Please note one thing about the multiple FILE based CUEs: any given FILE should appear in a CUE file at most once!
# CUE sheets in library
Library supports ONLY the associated .cues which means you need to name your .cues just like their associated media files, otherwise library scanner won't recognize them.
In library mode some features are absent, namely: CUE can still link to multiple files but only the songs coming from the file with the name associated with the CUE will be used!
For example, in this situation...
C:\songs\best\song1.wav
C:\songs\best\song2.wav
C:\songs\best\song1.cue
FILE song1.cue WAVE
... METADATA...
FILE song2.cue WAVE
... METADATA...
... all sections coming from the song2.wav file won't appear in the library (or rather the file song2.wav will appear as if there was no .cue related at all).
Please note that when rescanning the library, a song is marked as changed (which means it'll get updated) when either it's media file has changed or it's associated CUE file has changed. Also, when a CUE sheet that was used by library song sections gets deleted, the associated song sections are deleted from it too and the only thing that's left is the 'raw' media file like there was no CUE support in the first place.
# Embedded CUEs
Embedded CUEs are currently not supported and won't be supported until at least 0.8 version of Clementine. If you'd really like to see this feature, vote for this issue: issue #1276
# CUEs and invalid media files
Some formats (like APE) are not recognized by the tag library which Clementine's using. That means you cannot load such files (let's call those 'invalid') into Clementine. Try dropping such a song into playlist - the request will be ignored.
But... If you have a CUE related to such an invalid file, you'll be able to load it into playlist and possibly even play it! It's this way because all CUE related / associated songs are considered valid, even if they don't exist and in some situations (for example with APE files) Clementine might be able to play a media file while simultaneously not being able to read it's tags.
Keep in mind though that while you'll be able to load a CUE + invalid song pair into playlist, such a pair won't ever get into the library!
# Encoding
Unfortunately the CUE sheet standard is not specifying an encoding. There's a SLIGHT chance that Clementine will recognize any encoding out there... but if you don't want to see any weird characters in your tags, please convert all your CUEs to UTF because UTF (UTF-8 for example) is the only encoding family that's fully supported.
# Updating from Clementine 0.6 or earlier
When upgrading from version 0.6 or earlier, Clementine will require a full library rescan to see your CUEs. The fact will be detected by the player and it will provide you with a handy dialog during the update:
http://student.agh.edu.pl/~bara/rescan_notice.png
If you won't decide to do a full library rescan at this moment, remember to do it later using the "Do a full library rescan" option from the "Tools" menu!

72
FAQ.md Normal file

@ -0,0 +1,72 @@
# Frequently asked questions
<wiki:toc max_depth="1" />
## I can't seek through MP3s
The MP3 decoder in gstreamer's ffmpeg plugin doesn't support seeking through MP3s, you should install the one in gstreamer's ugly plugins package instead.
Ubuntu:
sudo apt-get install gstreamer0.10-plugins-ugly
Fedora:
su -c "yum install gstreamer-plugins-ugly"
## Nothing else can play sound while Clementine is running
Make sure you have pulseaudio and gstreamer's pulseaudio plugin installed.
Ubuntu:
sudo apt-get install pulseaudio gstreamer0.10-pulseaudio
Fedora:
su -c "yum install pulseaudio gstreamer-plugins-good"
## I can't play MP3s in openSUSE
openSUSE's gstreamer0_10-plugins-ugly package is incomplete, and doesn't contain any mp3 codecs. You should add the Packman repository ([instructions on the openSUSE website](http://en.opensuse.org/Additional_package_repositories)) and install the `gstreamer0_10-fluendo-mp3` package.
## I get a missing dependency on `gstreamer0.10(decoder-audio/mpeg)(mpegversion=1)(layer=3)` on Fedora
Fedora doesn't come with MP3 support built-in. You need to add the rpmfusion repositories and install gstreamer-plugins-ugly as explained in the [unofficial FAQ](http://www.fedorafaq.org/#mp3).
## Why doesn't Clementine use MySQL?
Clementine uses [sqlite](http://sqlite.org/) to store metadata for the songs in your library, as well as your playlists and devices. We've found that sqlite provides great performance even on huge libraries (300,000+ songs), and Clementine uses the [fts plugin](http://www.sqlite.org/fts3.html) to make searching even faster. We see no benefit in supporting other database backends as well as or instead of sqlite, and it would make the code much more complicated and difficult to maintain.
## Why doesn't Clementine use Phonon/VLC/Xine/!MyFavouriteSoundEngine?
GStreamer is the only audio backend we have found that supports our featureset.
### Phonon
- Does not support getting the raw audio stream for use in analysers and visualisations.
- No Hypnotoad support.
### VLC
- Has buffer under-run problems.
- Extracting raw audio data requires building a separate plugin.
- No Hypnotoad support.
### Xine
- Poor windows support.
- No Hypnotoad support.
## Where is Clementine's database?
Clementine stores all the information about your library in its sqlite database. This is in a different place depending on what operating system you use:
- On **Windows**: `%USERPROFILE%\.config\Clementine\clementine.db` (where `%USERPROFILE%` is `C:\Users\<username>` on Windows 7 and Vista, or `C:\Documents and Settings\<username>` on XP)
- On **Linux**: `~/.config/Clementine/clementine.db`
- On **Mac OS X**: `~/Library/Application Support/Clementine/clementine.db`
## Is Clementine CPU hungry?
This depends on the hardware you're running clementine on. On an Intel i5 quad core, clementine uses around 1% CPU on normal playback. When scanning the library, or doing other background jobs, it can be as high as 25% for one CPU. On machines, like netbooks (e.g. eee pc 701 or 901) with an Intel Atom CPU running at 600Mhz, clementine may use around 40% CPU on normal playback and when doing background jobs its CPU usage can go up to 80%.
Updating the database can cause some temporary playback problems (stuttering) on these machines. Especially if the storage is provided by USB sticks, SD cards or over the network (wifi). Normally, these problems disappear when the database is up to date.
If you want to minimize CPU usage of clementine, you can do the following things:
- You can disable the analyzer at the bottom of the window (right click on it and choose "No analyzer"),
- Otherwise, you can uncheck "Show a glowing animation on the current track" in the preferences.

67
GSoC2010-Ideas.md Normal file

@ -0,0 +1,67 @@
# Ideas for Google Summer of Code 2010
# Status
<table>
<tr><td>*This is the ideas page from last year's (2010) Google Summer of Code. For this year's ideas page, see [</table>
# Ideas
Here are some ideas that we've thought up that are about the right size for students to take on over the summer. Keep in mind that these are only suggestions - we'd love someone to come up with some entirely new feature we hadn't thought of before!
## iPod and mobile device support
This is a big set of features that we want to get in to Clementine before version 1.0. Amarok had great support for MP3 players, and we want something even better. Taking on this project would involve some or all of the following:
- Design a C++ interface for supporting and abstracting away the differences between different types of device. Ideally it should be possible for a new class to be dropped in to support a new type of MP3 player. The interface should allow the following operations:
- Checking if there are any supported devices attached to the system.
- Monitoring for new devices (using HAL, Solid, etc.) and emitting a signal when the user plugs one in.
- Listing music on the device.
- Copying music to/from the device.
- Design and implement a GUI that lets the user see which devices are connected and copy files to/from each one.
- Allow the user to select files, folders, artists or albums to keep synchronised between the library and a device.
- Support (an implementation of your interface) for iPods (maybe using libgpod) and generic removable-storage.
This is a big project, and we'd be quite happy with a proposal that only tackled a couple of these points.
## Scripting support
Other music players have had a lot of success allowing users to create scripts that run inside the application and add new features. We'd like some scripting bindings for Clementine, and a GUI for creating and loading scripts. Some ideas:
- Python is probably a good choice for scripting language, although QtScript, JavaScript, LUA or maybe even Perl would be ok too. Bonus points if the system is flexible enough for new languages to be added easily.
- Create interfaces (and tidy the existing ones where appropriate) for the big classes in Clementine - such as the library, the playlist and the player.
- Design and implement a GUI that lets the user see what scripts are available, enable/disable them, and add new ones from disk.
## DBUS support
This is loosely related to scripting support above. It would be nice to be able to control Clementine over DBUS or through the commandline. A DBUS interface should be created that allows a user to:
- Query information about the current track (metadata, album art, etc.)
- Receive notifications when the current track changes
- Query the songs in the library
- Query the songs in the playlist
- Add new songs to the playlist
- Control the player directly (ie. next, previous, stop, pause)
- Notify other apps on certain events (eg. new track started)
## Podcast support
We'd like users to be able to browse and subscribe to Podcasts through Clementine. This would probably involve doing some or all of:
- Looking for some big podcast directories on the internet, and finding whether they have public APIs for fetching content.
- Designing a C++ interface for communicating with these podcast directories. Ideally a new class could be dropped in to add support for a new podcast directory.
- Designing a kind of "manager" class that is responsible for keeping a list of these podcast directories and updating every week/month.
- Designing and implementing a GUI that lets the user browse and search through lists of podcasts (and adding their own by URL).
- Letting the user subscribe to individual podcasts. Clementine should then check the podcast for updates at some predetermined interval, download the newest items, make them available in a list in the GUI somewhere (probably the "Radio" tab) and finally show a notification telling the user that new stuff is available.
## Automatic tag management
There are a couple of other applications available that will automatically fix untagged files in your music collection. It would be great if Clementine could do this too!
- Find some way to identify MP3s (probably using a service like musicbrainz) that has a public API.
- Add some menu item or dialog to the GUI that allows the user to either select individual files for retagging, or that automatically finds badly tagged files in the library.
- Write some code to process files and retag them if necessary.
## Other ideas
The ideas above are by no means exhaustive - we'd welcome new suggestions that we haven't thought of before! If you need some inspiration check out the [http://code.google.com/p/clementine-player/issues/list issues list](GSoC2011Ideas].*</td></tr>) or the [TODO list in SVN](http://code.google.com/p/clementine-player/source/browse/trunk/TODO). If nothing there sounds interesting then feel free to suggest your favourite feature from another music player :-)

192
GSoC2011-Ideas.md Normal file

@ -0,0 +1,192 @@
# Ideas for Google Summer of Code 2011
<wiki:toc max_depth="3" />
# Status
Clementine wasn't accepted to GSoC as a mentor organisation this year, but we'll keep this list of ideas here anyway for reference.
# Ideas
Here are some ideas that we've thought up that are about the right size for students to take on over the summer. Keep in mind that these are only suggestions - we'd love someone to come up with some entirely new feature we hadn't thought of before!
All ideas below will require some knowledge of C++. An indication of the types of additional skills involved is given beneath each idea. These are not necessarily requirements - the whole idea of Summer of Code is to give you experience in technologies you've never used before, so you should be able to learn what you need as you go.
## How to apply
The list of GSoC mentoring organisations hasn't been announced yet ([see the timelime](http://www.google-melange.com/document/show/gsoc_program/google/gsoc2011/timeline)) but if you think you might be interested in applying:
- Join the IRC channel #clementine on [Freenode](http://freenode.net/) and subscribe to [the mailing list](http://groups.google.com/group/clementine-player).
- Check out the Clementine source code from Subversion and make sure you can compile it.
- [How to check out the source code](http://code.google.com/p/clementine-player/source/checkout).
- [[Compiling From Source|How to compile from source on Linux]]. It's possible to compile on Mac OS X or Windows as well but it's quite a bit more difficult.
- *Use* Clementine - find out what it can do and where all the features are. Try listening to some internet radio or copying some songs to your iPod. More importantly: find out what it can't do or what you think it could do better :)
- Familiarise yourself with the source code.
- Consider submitting a patch to fix a bug or implement a feature. We've marked some issues with the [PaperCut](http://code.google.com/p/clementine-player/issues/list?q=label:PaperCut) label in the issue tracker - these are small bugs that should be suitable for people without much experience with our code. If you need any help please ask in IRC or email the mailing list.
## Easy
### Compact view
Clementine's main window is really big, and at the moment it's the only way of interacting with the player (short of using the commandline or DBUS remote controls). There's an opportunity for a student who's keen on user-interface design to make a smaller more compact version of the interface that users could switch to instead.
This has been done before in [Amarok 1](http://amarok.sourceforge.net/amarok_20040203.png) as well as the classic players like [XMMS](http://userserve-ak.last.fm/serve/_/4585243/XMMSScrobbler+205.jpg) and [Winamp](http://teamnirvana.com/blog/wp-content/uploads/2009/09/winamp2.gif). There are plenty of ways those interfaces could be improved though, maybe by:
- Adding some quick-search bar (like Google Suggest) that would let a user search the library and quickly start playing a new song.
- Doing some cool effects on systems that support it, like [blur-behind on Windows Vista and Windows 7](http://msdn.microsoft.com/en-us/library/aa969537(v=vs.85).aspx).
|| **Difficulty** || Easy ||
|| **Labels** || GUI design ||
|| **Issue** || [issue 208](https://github.com/clementine-player/Clementine/issues#issue/208) ||
## Moderate
### Music store integration
Integrated music stores in music players have been getting more and more popular recently. The ability to buy music from inside a music player is already implemented in many mainstream applications for various shops available online.
Our goal here would be to incorporate support for at least one shop (let's say, 7digital.com) into Clementine while, at the same time, making it possible for other developers to add support for different stores in the future.
At the very least, integration should allow the music store's website to be browsed from a web-browser within Clementine. Integrating this into the existing user interface will be challenging, and the store should probably be shown in-place of the playlist while active. Other possible ideas include:
- A download manager (probably shown in the sidebar somewhere) so the user can monitor the progress of their downloads, pausing and resuming them as necessary.
- The ability to download directly to the library, and organise (rename) downloaded files automatically.
- Secure storage of credentials (usernames/passwords) for the music store websites.
|| **Difficulty** || Moderate ||
|| **Labels** || Networking, !WebKit, GUI design ||
|| **Issue** || [issue 908](https://github.com/clementine-player/Clementine/issues#issue/908) ||
### New types of dynamic playlist
Clementine supports dynamic playlists - these are special kinds of playlists that are generated by algorithms using certain criteria. The dynamic playlists in Clementine at the moment are quite simple - the user can enter in a simple query like "Genre == Rock and Rating > 0.5", and songs matching that query are added to the playlist. We'd like to have some algorithms that were "smarter" about the songs they added, maybe using online services to find songs that were similar to other artists or that were tagged by other users as belonging to a certain genre.
Some ideas we've thought about:
- Using the [last.fm API](http://www.last.fm/api/show?service=119) to find songs similar to a given artist or tag.
- Using the [echonest API](http://developer.echonest.com/docs/v4/artist.html#similar) to find songs similar to a given artist or tag.
- Support [advanced echonest searches](http://developer.echonest.com/docs/v4/artist.html#search), and let the user enter queries like "happy pop songs from the 70s".
- Make our query-based searches more useful by adding "fuzzy matching", so the user could search for, for example, "songs from around 1970". [Amarok 2 does this already](http://amarok.kde.org/blog/archives/767-Introducing-Fuzzy-Biases.html).
From a coding point of view Clementine already supports modular dynamic playlist "generators", so you should be able to focus on the algorithms without worrying about having to dig about in Clementine's code too much. A fun alternative (or additional) idea would be to add bindings for the dynamic playlist generators to our new Python scripting API, so developers could write new generators as Python plugins.
There's some more discussion about this idea in [issue 273](https://github.com/clementine-player/Clementine/issues#issue/273) and [issue 1336](https://github.com/clementine-player/Clementine/issues#issue/1336).
|| **Difficulty** || Moderate ||
|| **Labels** || Algorithms, REST APIs ||
|| **Issue** || [issue 273](https://github.com/clementine-player/Clementine/issues#issue/273) ||
### Moodbar
Amarok supports something called a [Moodbar](http://amarok.kde.org/wiki/Moodbar) - a replacement for the track seek-slider that shows different colours depending on the tempo and "mood" of the song at different places. It would be nice to have something like this in Clementine as well.
There is already a gstreamer plugin for analysing a song and generating the moodbar data, so it would be quite easy to implement in Clementine which already uses gstreamer for its playback. As an extension, a student could look at ways to improve or change the [Moodbar algorithm](http://cratoo.de/amarok/ismir-crc.pdf) to make it produce more visually pleasing output.
|| **Difficulty** || Moderate ||
|| **Labels** || Algorithms, DSP, Graphics ||
|| **Issue** || [issue 328](https://github.com/clementine-player/Clementine/issues#issue/328) ||
### Context view
At the moment Clementine has "artist info" and "song info" panes that fetch information from the internet about the song you're currently playing. We'd like to improve this feature by adding information that comes from your local library as well, such as:
- What other albums you have by this artist.
- What other songs you have that are similar to this one (the interpretation of "similar" is an excercise for the reader ;-)).
- Which songs by this artist you've rated the highest.
- How long ago you last listened to this album, and the first time you ever played it.
This task would involve some user interface work and could involve some clever algorithms or statistical analysis.
|| **Difficulty** || Moderate ||
|| **Labels** || Algorithms, GUI ||
|| **Issue** || [issue 1507](https://github.com/clementine-player/Clementine/issues#issue/1507) ||
### Party mode
After you've prepared a playlist and started its playback, the playlist view may become unnecessary for a while. In such cases we could utilize the huge amount of space the playlist view normally occupies for another type of view.
One example would be "party mode" where the currently playing song would be thoroughly presented. This view would contain some contextual information about the song (and possibly also about the previous and the next song) including cover, basic metadata, statistics and, of course, karaoke enabled lyrics.
Issue 1427 has an attached mockup of this feature, created by one of our users.
|| **Difficulty** || Moderate ||
|| **Labels** || GUI design ||
|| **Issue** || [issue 1427](https://github.com/clementine-player/Clementine/issues#issue/1427) ||
### CD playback, ripping and burning support
Clementine is great at playing music on the internet and from your hard disk, but at the moment it's no use for people with large CD collections. There are three different tasks here:
- Add support for playing music from CDs. GStreamer supports playing "cdda://" URLs already, so the tricky bit will be adding this to Clementine's user interface in a nice way. Ideally Clementine would fetch the track names from the internet using services like [Gracenote](http://www.gracenote.com/) or [freedb](http://www.freedb.org/).
- Rip tracks from CDs, encode them to mp3 (or flac, ogg, etc.) and save them to the library. Again, GStreamer can already do the ripping and the transcoding, the difficult bit will be plugging everything together and making it work nicely in Clementine's interface.
- Burning tracks to CDs. This will require using the platform's native CD-burning APIs (like [IMAPI on Windows](http://msdn.microsoft.com/en-us/library/aa939967.aspx)), or running external CD-burning programs (like Brasero or K3B on Linux).
|| **Difficulty** || Moderate ||
|| **Labels** || GStreamer, Native APIs ||
|| **Issues** || [issue 27](https://github.com/clementine-player/Clementine/issues#issue/27), [issue 701](https://github.com/clementine-player/Clementine/issues#issue/701) ||
### Make it pink
One of Clementine's oldest and most critical bugs is that [it is not pink](http://code.google.com/p/clementine-player/issues/detail?id=219). Giving a Clementine a brand new, pink, interface (with a sparkle feature and, of course, a cat) would be a perfect project!
<table>
<tr><td>**Difficulty**</td><td>Moderate</td></tr>
<tr><td>**Labels**</td><td>GUI design</td></tr>
<tr><td>**Issue**</td><td>[issue 219](https://github.com/clementine-player/Clementine/issues#issue/219)</td></tr>
</table>
## Hard
### Podcast support
We'd like users to be able to browse and subscribe to Podcasts through Clementine. This would probably involve doing some or all of:
- Looking for some big podcast directories on the internet, and finding whether they have public APIs for fetching content.
- Designing a C++ interface that can be implemented by classes for communicating with these podcast directories. Ideally a new class could be dropped in to add support for a new podcast directory.
- Designing a kind of "manager" class that is responsible for holding a list of these podcast directories and updating the list every week/month/day.
- Designing and implementing a GUI that lets the user browse and search through lists of podcasts (and adding their own by URL).
- Letting the user subscribe to individual podcasts. Clementine should then check the podcast for updates at some predetermined interval, download the newest items, make them available in a list in the GUI somewhere (probably the "Internet" tab) and finally show a notification telling the user that new stuff is available.
- Optional: automatically sync new items in the podcast to removable devices (iPods). Users would be able to plug in their device and Clementine would automatically copy new files to it, and optionally delete ones from the device that had been listened to, or were older than a certain date.
|| **Difficulty** || Hard ||
|| **Labels** || C++ object orientation, Networking, GUI design ||
|| **Issue** || [issue 44](https://github.com/clementine-player/Clementine/issues#issue/44) ||
### Various providers for cover art, scrobbling and autotagging features
Right now, those are monopolized:
- when we say 'covers', we think last.fm
- when we say 'scrobbling', we think last.fm
- when we say 'autotagging' we mean !MusicBrainz
On the other hand, we have radio services which got refactored as a part of upcoming 0.7 version. A common interface was extracted and made available for scripts. This means that adding a new radio to Clementine is now as simple as writing a bunch of code in Python.
It would be great if the aforementioned features got this treatment too. If there was a common scripting API for those, other people could enhance Clementine without the need to dig into it's codebase.
Whether it's covers from Amazon, scrobbling with libre.fm or autotagging with last.fm or discogs, all those would help to make working with Clementine a better experience.
|| **Difficulty** || Hard ||
|| **Labels** || C++ object orientation, REST APIs ||
|| **Issues** || [issue 1](https://github.com/clementine-player/Clementine/issues#issue/1), [issue 918](https://github.com/clementine-player/Clementine/issues#issue/918), [issue 1168](https://github.com/clementine-player/Clementine/issues#issue/1168) ||
### DLNA or DAAP for sharing music over the local network
Lots of devices and music players are able to share the user's music collection with other devices over the network. This lets you, for example, play music from a NAS (Network Accessible Storage) box through the speakers attached to your PS3. Currently the two main standards for this are:
- [DAAP](http://en.wikipedia.org/wiki/Digital_Audio_Access_Protocol) - Developed by Apple for iTunes but supported by most music players.
- [DLNA](http://en.wikipedia.org/wiki/Digital_Living_Network_Alliance) - Developed originally by Sony but now used by a number of major hardware manufacturers.
Ideally Clementine should be able to:
- Export the user's local library to other devices using these standards.
- Play music exported by other devices, automatically discovering them on the network.
This is quite a big project so we'd be happy to accept proposals that tackled only one of the two standards, as long as the design was flexible enough that implementations for other standards could be added later.
|| **Difficulty** || Hard ||
|| **Labels** || Networking, Library, C++ object orientation ||
|| **Issue** || [issue 34](https://github.com/clementine-player/Clementine/issues#issue/34) ||
# Other ideas
The ideas above are by no means exhaustive - we'd welcome new suggestions that we haven't thought of before! If you need some inspiration check out the [issues list](http://code.google.com/p/clementine-player/issues/list). If nothing there sounds interesting then feel free to suggest your favourite feature from another music player :-)

49
Handling-Of-Unplayable-Files.md Normal file

@ -0,0 +1,49 @@
# How does handling of unplayable files work in Clementine's case?
<wiki:toc max_depth="2" />
# Dictionary
**valid song** - a song is valid if it exists and is playable
**existing song** - a local media file that's on your disk or a stream that is reachable at the moment
**playable song** - a media file or stream with a format that your GStreamer's installation understands and can play
# General rule
A general rule is to grey out a song in the playlist if it's not valid.
Also, if a song was once invalid and at some point it becomes valid again, we want it to be repainted black.
Be aware that we are NOT monitoring your playlist items in the background hence you won't see any unexpected "flickering" of colors in your playlists. All the factors that might trigger a change of colors are described below.
# Built-in features
## Playing a once valid song
Whenever you try to play a song that was once valid, Clementine will check if the file or stream is still valid.
If that's not the case, the item will be greyed out in the playlist view and Clementine will automatically jump to a next song.
All this applies to both manual and automatic playback requests.
## Playing a once broken song
Whenever you try to play a song which was once broken and is hence greyed out, Clementine will recheck it's validity.
If the song is now valid again, it's metadata will be reloaded and the song will be repainted black in the playlist view. The playback will start normally and everything will look like there was nothing wrong with the file in the first place.
All this applies to both manual and automatic playback requests.
## Startup of the player
If you have the "Grey out non existent songs in my playlists" setting on (check out the "Behavior" section of Clementine's settings), a scan of all your playlist items will be ran each time the player is started.
Clementine will scan all of your playlists and:
- all local songs that exist will be painted black
- all local songs that don't exist anymore will be greyed out
Please note that this cannot detect unplayable items - only deleted ones.
Even though the setting is turned off by default you shouldn't be afraid of turning it on. The scan is asynchronous and pretty lightweight.

60
Library-Scanning.md Normal file

@ -0,0 +1,60 @@
# A few words about the process of library scanning and rescanning
<wiki:toc max_depth="1" />
# Scanning files and Clementine's database
When you first add a folder to your library in the Preferences dialog, Clementine will scan it and all it's subfolders looking for media files. Every correct media file will get into your library with all of it's metadata, whether the metadata is coming from the media file itself (things like ID3 tags) or from another source like is the case with CUE associated songs.
http://student.agh.edu.pl/~bara/new_library_folder.png
All the metadata goes straight into your Clementine's database. The database is the heart of Clementine. It let's us, developers, provide you with features like a view of your songs in form of a tree-like structure (that's the Library view), fast lookup of songs you need, ability to create smart playlists filtered by various conditions etc.
Of course, most of the data in the database can and will change with time. You can do things like: update a song's metadata, move an album under 'Various artists', change it's cover art or you can just play music. The last one affects the database because we're keeping things like the last played time, play count and score there.
Remember that when you're removing a folder from library, you're also removing all the statistics associated in the database with it. You'll always be able to add the folder to the library again but the statistics are gone forever.
# Monitor library for changes
In "Preferences / Music Library", there's a "Monitor library for changes" option.
http://student.agh.edu.pl/~bara/monitor_for_changes.png
Turning it on will make Clementine watch your library FOLDERs for changes. If a folder monitor notifies Clementine of change, the player will rescan that directory and all of it's subdirectories.
During a scan, only the files for which their mtime (modification time) has changed since the last scan, will get examined. This of course includes files not yet in the library and those library files which got deleted. Other library songs won't go through any changes.
Please remember that we're not watching your FILEs for changes, only FOLDERs. This is by design due to shortage of resources on many filesystems.
What this means is that not every change will get noticed - only those which somehow "touch" the folder will trigger a partial rescan. The behaviour of Clementine depends on your filesystem here but the bottom line is - you should be aware of that issue.
If you cannot seem to force Clementine to update a song, try one of these methods:
- add or remove a file from the folder that contains your song
- rename the folder that contains your song or readd it to your library (be aware that those methods will remove the statistics associated with all of the folder's songs)
- a "Full library rescan" will make sure the song is updated but it takes some time depending on size of your library
Also, remember that if you have "Monitor library for changes" option off, you'll need to run "Update changed library folders" action manually every time you'll want to see library changes applied.
# Update changed library folders
http://student.agh.edu.pl/~bara/update.png
This menu option scans all your library roots in search for changes. If it finds a change in a folder's mtime, the scan goes deeper. This of course suffers from the same issues that were described above - the depth of search depends on modification times of folders.
You should treat the feature like a helper and not the ultimate problem solver. It's lightweight but in some cases won't help Clementine see the changes you made (especially using some external tool).
The workarounds above apply here too but to make them fully work you'd need to apply those on every level of the tree of your library folders.
http://student.agh.edu.pl/~bara/update_on_start.png
This type of scan is launched during Clementine's startup, when you have the "Update the library when Clementine starts" option on ("Preferences / Music Library").
# Do a full library rescan
This feature is your last resort will-work-in-any-circumstances friend.
http://student.agh.edu.pl/~bara/full_rescan.png
This type of scan treats every folder it goes through and every file in all of the folders like they've changed since the last scan which of course means, everything will get updated to the current version. The most important thing here is, your statistics (like rating or playcount) will be preserved.
The full collection rescan goes through all your library roots and all of their subfolders. Obviously this might take some time, especially when your library is huge but still we'd recommend doing a full rescan every now and then.

63
Library-View-Modes.md Normal file

@ -0,0 +1,63 @@
# Description of library view's modes
<wiki:toc max_depth="1" />
# Introduction
There are three modes you can choose from:
- all songs mode (the default one)
- duplicated songs mode
- untagged songs mode
Modes define which songs will be shown in the library's tree. The alternative modes (non-default ones) are supposed to help you maintain your library.
You can find the mode changer by clicking the 'wrench icon' near library's filter:
http://student.agh.edu.pl/~bara/lib_modes.png
# All songs mode
Nothing special to say here - all songs from the library will be visible in library's tree. This is the default mode.
You can use all other features of library view (filtering, grouping and the age limit feature) in this mode.
This mode is intended for normal everyday usage:
http://student.agh.edu.pl/~bara/lib_all.png
# Only duplicates mode
In this mode only the songs for which the (artist, album, title) tuple is found more than once in the library will be shown. The feature is case sensitive which means:
1. those are duplicates:
- Antimatter - A Dream For The Blind - Lost Control - /!LostControl.mp3
- Antimatter - A Dream For The Blind - Lost Control - /other/!LostControl.mp3
1. those are not duplicates (different album's case):
- Antimatter - a dream for the blind - Lost Control - /!LostControl.mp3
- Antimatter - A Dream For The Blind - Lost Control - /other/!LostControl.mp3
1. those are not duplicates (different album):
- Antimatter - Live - Lost Control - /!LostControl.mp3
- Antimatter - A Dream For The Blind - Lost Control - /other/!LostControl.mp3
In this mode you can use the grouping and age limit features but you cannot use filtering!
This mode is intended to help you identify those songs which appear more than once on your disk which is a possible waste of space. You can use Clementine's 'Remove from disk' feature to dispose of the unwanted copies:
http://student.agh.edu.pl/~bara/lib_duplicates.png
# Only untagged mode
In this mode only the songs which have at least one of the (artist, album, title) tags empty will be shown. For example:
1. this song is considered tagged:
- Antimatter - Live - Lost Control
1. this song is considered untagged (missing title):
- Antimatter - Live -
1. this song is considered untagged (missing album and title):
- Antimatter - -
In this mode you can use the grouping and age limit features but you cannot use filtering!
This mode is intended to help you identify those songs which will appear in weird places in the library tree view. You can fill their tags using for example the 'edit tags' dialog, and possibly also it's "autocomplete tags" feature:
http://student.agh.edu.pl/~bara/lib_untagged.png

123
MPRIS.md Normal file

@ -0,0 +1,123 @@
# Controlling Clementine from the commandline with DBus and MPRIS
# Introduction
Clementine can be controlled remotely over DBus. [DBus](http://www.freedesktop.org/wiki/Software/dbus) is a message bus that lets applications on Linux talk to each other. It replaces DCOP that was used by KDE 3 and Amarok 1.4.
This guide will show you how to control Clementine from the commandline and from Python scripts.
## The specifications
MPRIS is a common API for controlling music players over DBus. Clementine supports MPRIS versions 1 and 2:
- [MPRIS 1](http://xmms2.org/wiki/MPRIS)
- [MPRIS 2](http://www.mpris.org/2.1/spec/)
# Using the command line
Clementine has two names on the bus: `org.mpris.clementine` (the MPRIS 1 interface) and `org.mpris.MediaPlayer2.clementine` (for MPRIS 2). You can use the `qdbus` application to explore which objects and methods are available on each one, for example:
$ qdbus org.mpris.clementine
/
/Player
/TrackList
/org
/org/mpris
/org/mpris/MediaPlayer2
$ qdbus org.mpris.clementine /
method QString org.freedesktop.MediaPlayer.Identity()
method void org.freedesktop.MediaPlayer.Quit()
method QDBusVariant org.freedesktop.DBus.Properties.Get(QString interface_name, QString property_name)
method QVariantMap org.freedesktop.DBus.Properties.GetAll(QString interface_name)
method void org.freedesktop.DBus.Properties.Set(QString interface_name, QString property_name, QDBusVariant value)
method QString org.freedesktop.DBus.Introspectable.Introspect()
$ qdbus org.mpris.clementine / org.freedesktop.MediaPlayer.Identity
Clementine 0.7
You can see that you need to give 3 things when you use qdbus:
1. The **bus name** identifying the application you want to talk to: `org.mpris.clementine`
1. The **object path** identifying which part inside that application you want. We used `/` to list the methods on the root object.
1. The **method name** that you want to call: `org.freedesktop.MediaPlayer.Identity`. The method name is only really `Identify` in this case - everything before the final dot is known as the **interface name**.
qdbus is great for finding out what methods are available on DBus objects. It also supports tab completion.
## What song is playing now?
The GetMetadata MPRIS 1 method gives you information about the currently playing song:
$ qdbus org.mpris.clementine /Player org.freedesktop.MediaPlayer.GetMetadata
album: Monty Python Sings
artist: Monty Python
arturl: file:///tmp/clementine-art-PE4553.jpg
audio-bitrate: 128
audio-samplerate: 44100
location: file:///stuff/Music/Monty Python/Monty Python Sings/Eric The Half A Bee.mp3
mtime: 129000
time: 129
title: Eric The Half A Bee
tracknumber: 14
Using MPRIS 2 to get metadata is a little more difficult because it's exposed as a DBus *property* instead of a *method* that returns information. You have to call the `org.freedesktop.DBus.Properties.Get` method and give it the name of the property you want to get as an argument:
$ qdbus org.mpris.MediaPlayer2.clementine /org/mpris/MediaPlayer2 org.freedesktop.DBus.Properties.Get org.mpris.MediaPlayer2.Player Metadata
mpris:artUrl: file:///tmp/clementine-art-PE4553.jpg
mpris:length: 129000000
mpris:trackid: /org/mpris/MediaPlayer2/Track/27
xesam:album: Monty Python Sings
xesam:artist: Monty Python
xesam:autoRating: 50
xesam:contentCreated: 2011-01-03T23:41:27
xesam:lastUsed: 2011-04-01T01:40:23
xesam:title: Eric The Half A Bee
xesam:trackNumber: 14
xesam:url: file:///stuff/Music/Monty Python/Monty Python Sings/Eric The Half A Bee.mp3
Both MPRIS 1 and MPRIS 2 work in Clementine so you can use whichever one you prefer, although MPRIS 1 is usually a bit more straightforward.
## Controlling playback
The `/Player` object has a load of methods like `Play`, `Pause`, `PlayPause`, `Stop`, `Next` and `Prev` that can be used to control the player:
$ qdbus org.mpris.clementine /Player org.freedesktop.MediaPlayer.Pause
Some methods, like `VolumeSet`, take an argument. You just pass this to qdbus after the method name:
$ qdbus org.mpris.clementine /Player org.freedesktop.MediaPlayer.VolumeSet 50
$ qdbus org.mpris.clementine /Player org.freedesktop.MediaPlayer.VolumeSet 100
See [the MPRIS specifications](MPRIS#The_specifications) for information about the other methods that Clementine supports.
# Using Python
It's easy to use the [dbus python module](http://dbus.freedesktop.org/doc/dbus-python/doc/tutorial.html) to control Clementine from a Python script.
import dbus
# Clementine lives on the Session bus
session_bus = dbus.SessionBus()
# Get Clementine's player object, and then get an interface from that object,
# otherwise we'd have to type out the full interface name on every method call.
player = session_bus.get_object('org.mpris.clementine', '/Player')
iface = dbus.Interface(player, dbus_interface='org.freedesktop.MediaPlayer')
# Call a method on the interface
metadata = iface.GetMetadata()
print metadata["title"]
print metadata["artist"]
Notice we're calling the same `GetMetadata` method as we did in the section above with the commandline. It gives us back a dictionary that contains the same information that qdbus printed out before.
Controlling the player is done in the same way, we just call a different method on that interface:
iface.Play()
iface.Pause()
iface.VolumeSet(50)

15
Other-Downloads.md Normal file

@ -0,0 +1,15 @@
# Downloads for other distributions created by third parties
# Introduction
[Official Clementine downloads](http://code.google.com/p/clementine-player/downloads/list) are available for Ubuntu, Fedora, Windows and Mac OS X. The packages listed below have been provided by third parties for other distributions. If you'd like to have your own package added to this list then please leave a link in the comments section.
## Third party downloads
- A **Slackware** build script is available from http://slackbuilds.org/. Maintained by David Woodfall
- !PiSi packages for **Pardus Linux** are available from http://paketler.pardus-linux.org/P2009-free/, with [build files](http://svn.pardus-linux.org/paketler/P2009-free/clementine/) available separately. Maintained by Erdem Artan.
- for **Archlinux**, a `$ pacman -S clementine` will suffice, or for lastest svn snapshot it's [available](http://aur.archlinux.org/packages.php?ID=34981) in AUR or just `$ yaourt -S clementine-svn`
- **openSUSE** packages are available from http://software.opensuse.org/download.html?project=multimedia:apps&package=clementine

21
Packaging-Fedora.md Normal file

@ -0,0 +1,21 @@
# Packaging Clementine for Fedora
## Introduction
This guide is for creating the .rpm files that you see on the [downloads page](http://code.google.com/p/clementine-player/downloads/list?q=distro:fedora). **You probably don't need to do this**. You can download a Fedora package from the downloads page, or if you want to just compile Clementine yourself see [[Compiling From Source]].
## Before you begin
su -c "yum install mock rpmdevtools"
rpmdev-setuptree
su -c "usermod -a -G mock yourusername"
## Creating the package
cd bin
cmake .. -DMOCK_CHROOT=fedora-13-x86_64 \
-DRPM_DISTRO=fc13 \
-DRPM_ARCH=x86_64
make rpm
This should spit out a clementine.rpm in the `bin` directory.

26
Packaging-Ubuntu.md Normal file

@ -0,0 +1,26 @@
# Packaging Clementine for Ubuntu
## Introduction
This guide is for creating the .deb files that you see on the [downloads page](http://code.google.com/p/clementine-player/downloads/list?q=distro:ubuntu). **You probably don't need to do this**. You can download an Ubuntu package from the downloads page, or if you want to just compile Clementine yourself see [[Compiling From Source]].
## Before you begin
sudo apt-get install debhelper dpkg-dev pbuilder
Add the following to `/etc/pbuilderrc`:
COMPONENTS="main restricted universe multiverse"
Then:
sudo pbuilder create
## Creating the package
cd dist
./maketarball.sh
tar -xvzf clementine-_version_.tar.gz
cd clementine-_version_
cp -r ../../debian .
dpkg-buildpackage -rfakeroot -d -S
sudo pbuilder build ../*.dsc
sudo schroot -c lucid-32 pbuilder build ../*.dsc
The deb should now be in /var/cache/pbuilder/result

65
Portable-Devices.md Normal file

@ -0,0 +1,65 @@
# Using your iPod or portable media player with Clementine
# Introduction
Starting from version 0.5 Clementine has support for iPods, MTP devices (also known as Microsoft PlaysForSure) and USB mass storage devices.
<table>
<tr><td>**Device**</td><td>**Windows**</td><td>**Linux**</td><td>**Mac**</td></tr>
<tr><td>**iPod classic**</td><td><font color="green">supported</font></td><td><font color="green">supported</font>, requires libgpod</td><td><font color="green">supported</font></td></tr>
<tr><td>**iPod Touch, iPhone 3G/3GS**</td><td><font color="darkorange">supported if you have iTunes installed</font></td><td><font color="green">supported</font>, requires libgpod and libimobiledevice</td><td><font color="green">supported</font></td></tr>
<tr><td>**MTP**</td><td><font color="green">supported</font></td><td><font color="green">supported</font>, requires libmtp and GIO</td><td><font color="darkorange">flaky</font></td></tr>
<tr><td>**USB mass storage**</td><td><font color="green">supported</font></td><td><font color="green">supported</font></td><td><font color="green">supported</font></td></tr>
</table>
When you plug in a device it should show up automatically in the Devices tab on the left of the Clementine window. Double clicking on the device will open it and start searching for songs inside. You can copy songs to a device by right clicking them in the library or the playlist and selecting *Copy to device*.
http://www.clementine-player.org/screenshots/wiki/devices-small.png
# Types of device
## iPods
Clementine uses [libgpod](http://www.gtkpod.org/wiki/Libgpod) to read and write the iTunes database on your iPod. This is installed automatically if you download a binary package of Clementine, but if you are compiling from source make sure you have the libgpod and libgpod-dev packages installed before you start.
The classic iPod or iPod shuffle appear as USB mass storage devices are mounted and accessed directly by Clementine, but the iPod touch, iPhone and iPad use a different protocol and Clementine uses [libimobiledevice](http://www.libimobiledevice.org/) to access them. libimobiledevice requires usbmuxd which on **Windows** is installed by iTunes.
- **Show a list of songs:** <font color="green">works</font>
- **Copy songs to device:** <font color="green">works</font>
- **Copy songs from device:** <font color="green">works</font> for iPod classic, <font color="red">doesn't work</font> for iPod Touch, iPhone, iPad
- **Play songs:** <font color="green">works</font>
- **Find out which files are supported:** <font color="green">works</font>
## MTP
On **Linux** and **Mac**, MTP ([Media Transfer Protocol](http://en.wikipedia.org/wiki/Media_Transfer_Protocol)) devices are supported in Clementine through [libmtp](http://libmtp.sourceforge.net/). If you are compiling from source make sure you have the libmtp and libmtp-dev packages installed before you start.
On **Linux** you also need GIO and GVFS installed to be able to detect MTP devices.
On **Windows**, MTP support comes from the Windows Media Device Manager (WMDM). The Clementine setup program will check if you have this installed and automatically download it if required. WMDM supports other kinds of devices too, such as phones that run Windows CE.
MTP devices can sometimes be a bit temperamental. If you have problems copying songs to your device try unplugging it and plugging it back in, or restarting it.
- **Show a list of songs:** <font color="green">works</font>
- **Copy songs to device:** <font color="green">works</font>
- **Copy songs from device:** <font color="red">doesn't work</font>
- **Play songs:** <font color="red">doesn't work</font>
- **Find out which files are supported:** <font color="green">works</font>
## USB mass storage
Other USB devices that aren't music players, such as USB flash disks or memory cards, usually support the Mass Storage protocol. Clementine treats these as normal folders containing music, much like it does with the folders you add to your library. When you copy songs to a mass storage device you are able to choose a naming scheme for the filenames, this works in the same way as the Organise dialog.
On **Linux** Clementine uses either DeviceKit or GIO to detect mass storage devices. Clementine will try to mount devices as soon as you plug them in, but if a device doesn't show up try mounting it manually (using your file browser or the commandline).
- **Show a list of songs:** <font color="green">works</font>
- **Copy songs to device:** <font color="green">works</font>
- **Copy songs from device:** <font color="green">works</font>
- **Play songs:** <font color="green">works</font>
- **Find out which files are supported:** <font color="red">doesn't work</font>
# Automatic Transcoding
Clementine will try to find out what file formats your device can play and automatically convert any songs you try to copy across. If you want to turn off this behaviour, or change your preferred file format, right click on the device and choose *Device properties...*, then go to the *File formats* tab.
http://www.clementine-player.org/screenshots/wiki/devices-fileformats.png

162
Releasing.md Normal file

@ -0,0 +1,162 @@
# How to release a new version of Clementine
# Introduction
These instructions are intended for Clementine developers who want to release a new version to the public. If you just want to build Clementine from source, look at the CompilingFromSource page.
# Release candidate
It's usually best to make a release candidate about 1 week before the final release.
- Update the Changelog file by looking at the git log from the time of the last release. Make sure you don't include commits that were made in master during the last release cycle and cherry-picked into a release.
- Create a git branch for the release:
git checkout -b release-1.1
All development should still happen in the master branch, and any commits that need to go into the release should be cherry-picked from master into the release branch:
git cherry-pick -x [revision]
- Bump the version number of the branch. Edit the `cmake/Version.cmake` file and:
- Change the `CLEMENTINE_VERSION_MAJOR` and `CLEMENTINE_VERSION_MINOR` variables to match the version number.
- Uncomment `CLEMENTINE_VERSION_PRERELEASE`.
- Set `INCLUDE_GIT_REVISION` to `OFF`.
For example:
# Version numbers.
set(CLEMENTINE_VERSION_MAJOR 1)
set(CLEMENTINE_VERSION_MINOR 1)
set(CLEMENTINE_VERSION_PATCH 0)
set(CLEMENTINE_VERSION_PRERELEASE rc1)
# This should be set to OFF in a release branch
#set(INCLUDE_GIT_REVISION ON)
Commit this change. The commit will be merged back into trunk after the release is complete. Push the new branch to the repository with:
git push -u origin release-1.1
- Build the binaries. Go to the [builders page on buildbot](http://buildbot.clementine-player.org/builders) and scroll down to the `Force Selected Builds` section:
- Select the Deb and Rpm builders that you want to target. As a rule of thumb, we target the two most recent Fedora versions, all Ubuntu versions since the last LTS release, and Debian Squeeze.
- Select the MinGW-w64 Release builder and the Mac Release builder.
- Enter your username and password.
- In `Branch to build` enter the branch name that you created earlier (`release-1.1`).
- Click `Force build`.
Monitor the build on [the grid page](http://buildbot.clementine-player.org/grid). It will take 1-3 hours to build everything, depending on how many other builds were queued at the time.
- Build the source tarball. We don't have a buildbot step for this yet so you have to do it in your local checkout:
cd bin
cmake ..
cd ../dist
./maketarball.sh
This will create a .tar.gz file in the current directory with a name like `clementine-1.1.0rc1.tar.gz`.
- Gather all the binary and source packages together into one directory on your local machine. Buildbot will put the binary packages you told it to build into http://builds.clementine-player.org/
- If the set of packages you built was different to the last time we did a release, edit the constants at the top of the `dist/googlecode_upload_all.py` file. For example, you might need to add another Fedora or Ubuntu version. When it's up to date, run that script from the directory you copied all the packages into:
python ~/src/clementine/dist/googlecode_upload_all.py
- Send an email to the mailing list to announce the release candidate. You should include a short summary of the major features and link readers to the full changelog and the downloads page. For example: https://groups.google.com/forum/?fromgroups=#!topic/clementine-player/3jPLPYKVuAU
- Change the topic in the IRC channel to announce the release candidate and link to the downloads page. For example:
Clementine 1.1 Release Candidate out | http://code.google.com/p/clementine-player/downloads/list
# During the release candidate phase
- If any major bugs are found (or you have a new idea for nyanalyzer cat), make commits to master and then cherry-pick them across to the branch by:
git cherry-pick -x [revision]
# Final release
- At the end of the release candidate phase you should update the Changelog file with any changes that were done in master and then cherry-picked into the release branch. You should make this change to the Changelog in master and then cherry-pick it across, just like a normal bugfix.
- Bump the version number of the branch. Edit the `cmake/Version.cmake` file and:
- Comment out `CLEMENTINE_VERSION_PRERELEASE`.
For example:
# Version numbers.
set(CLEMENTINE_VERSION_MAJOR 1)
set(CLEMENTINE_VERSION_MINOR 1)
set(CLEMENTINE_VERSION_PATCH 0)
#set(CLEMENTINE_VERSION_PRERELEASE rc1)
# This should be set to OFF in a release branch
#set(INCLUDE_GIT_REVISION ON)
Commit this change to the release branch (don't put it in master yet).
- Build the binaries and the source tarball exactly the same as you did for the RC.
- While everything is building you can take 4 screenshots that demonstrate some of the new features in the new release. I try to make sure we have screenshots of each platform (Windows, OS X and Linux). Once you've taken 4 screenshots:
- Make sure you've checked out the `appengine` repository ([instructions](http://code.google.com/p/clementine-player/source/checkout?repo=appengine)) and installed the [appengine SDK for Python](https://developers.google.com/appengine/downloads).
- Put the full-sized screenshots in the `clementine-player.appengine/www.clementine-player.org/static/screenshots` directory. Follow the naming convention of all the other files in there.
- Make thumbnails of each screenshot:
cd ../thumbnails
./makethumbnail.sh ../screenshots/clementine-1.1-1.png
./makethumbnail.sh ../screenshots/clementine-1.1-2.png
./makethumbnail.sh ../screenshots/clementine-1.1-3.png
./makethumbnail.sh ../screenshots/clementine-1.1-4.png
- These images are stored in the appengine repository so we have them somewhere in version control, but they aren't actually served from appengine because we'd soon hit the bandwidth quota. You have to rsync them to images.clementine-player.org, which is hosted on Zaphod:
rsync -rav thumbnails screenshots zaphod:/var/www/clementine-player.org/images/
Verify that your images show up by looking in http://images.clementine-player.org/screenshots/
- Either commit these screenshots to the appengine repository now or do the next step first and commit everything in one go.
- Update the `www.clementine-player.org/data.py` file in the appengine repository with information about the new release:
- Update the `LATEST_VERSION` constant.
- Add a new dictionary to the `SCREENSHOTS` array.
- Add new entries to the `DOWNLOADS` array, one for each package we're building this time.
- If we've added a new Ubuntu or Fedora type, add it to `DISPLAY_OS`, `SHORT_DISPLAY_OS` and `OS_LOGOS`.
- Write a short paragraph describing the new stuff in the release and add it to the end of `NEWS`. Be sure to take today's timestamp by running:
python -c "import time; print int(time.time())"
- Update the list of features at the top of `main.html` in the same directory with any cool new features in this release.
- Run `make` in the `www.clementine-player.org` directory to update the language files.
- Check the site looks ok by running the appengine dev-appserver:
dev_appserver.py .
And then going to http://localhost:8080/ in a web browser.
- If everything looks good commit these changes to the appengine repository, but don't push to the live appengine site until everything else is done.
- Gather all the binaries together in a directory on your local machine and upload it to Google Code just as you did for the RC.
- Go to the downloads page on Google Code and mark all the old downloads as Deprecated. This includes the last stable version as well as the release candidate you uploaded a week ago.
- Give the newly uploaded files the Featured label so they show up on the home page.
- [Update the Google Code project summary](http://code.google.com/p/clementine-player/admin):
- Move the old news to the old news section and insert the news for this release. If you copy and paste the news you wrote for the website remember to convert any links into wiki markup style.
- Update the screenshot URLs.
- Add any new features to the list at the top.
There's no way to preview this summary before you save, and it's not version controlled, so be careful.
- Deploy the website to appengine:
- Update the `version` field in the `app.yaml` file to match the number of this release. Using a new app version number like this lets us test and maybe rollback this version of the website using Appengine.
- Push this version of the website by running:
appcfg.py update .
Test that this looks good by going to the special versioned appspot URL http://release-1-1.clementine-web.appspot.com/ (change the 1-1 part).
- Make this new version the default by going to the Versions tab on https://appengine.google.com/
- Don't forget to commit the change to the `app.yaml` file.
- Tag the release branch in git. Be sure to tag the exact revision that you released:
git checkout release-1.1
git tag -s 1.1
git push --tags
Sign the tag with a GPG key that's associated with you in Launchpad.
- Merge the release branch back into master.
git checkout master
git merge release-1.1
Also make a new commit in master to change `cmake/Version.cmake` and enable `INCLUDE_GIT_REVISION` again.
- Upload packages to the stable PPA.
cd dist
./uploadtoppa.sh tags/1.1 lucid
./uploadtoppa.sh tags/1.1 maverick
...
You'll need to do this once for each of the PPAs.
## TODO
- Emailing the list and updating the IRC topic
- Updating kde-apps.org and qt-apps.org
- Updating freshmeat
- Signing the OS X binary
- Updating the OS X and Windows sparkle feeds

46
Remote-Control-Dev.md Normal file

@ -0,0 +1,46 @@
# Developer documentation for the Clementine network remote
This page explains how the network remote works.
# Connections
When enabling the network remote, Clementine opens a TCP server socket on port 5500 (can be changed in the settings). It listens for incoming connections and checks their validity. If Clementine refuses non private ips, it drops the connection without any response.
# Communication
The communication between Clementine and its clients works via protocol buffers. Info on protocol buffer: http://code.google.com/p/protobuf/
You can find the protocol buffer file here: ext/libclementine-remote/remotecontrolmessages.proto
All send and received messages must contain the message "Message" with a messagetype, that is defined on the top of the file and the default protocol buffer file version. Most messages have a seperate type specific message inside "Message". When sending / receiving you have to fill / parse it.
## Connect
After the client connected to Clementine, it has to send a CONNECT message with the optional authentication code. If Clementine requires an auth code, Clementine will drop the client if any other messages are received with a DISCONNECT message which includes the reason.
Once the connect message was received, Clementine sends "first data" to the client. This contains the current track, all playlists, current volume, repeat and shuffe mode and, if in the connect message requested, all song metadata from all playlists.
## Control Clementine
You can control Clementine by sending "Message" with the control types like PLAY, PAUSE, STOP, LOVE, BAN, change track / playlist, etc. Clementine will execute the command immediatly.
## Clementine responses
Clementine will send the song metadata of the currenly played song after a track starts. If something changes, like volume, playlist songs, playlists, shuffle mode, repeat mode, it sends the change directly to the clients. You don't have to request a state, Clementine informs all clients directly.
## Keep alive
Clementine sends every 10 seconds a keep alive message. Use this to determine if the connection is lost.
## Disconnect
When Clementine closes, it sends a DISCONNECT message to all clients.
If the client want to disconnect, it should send a DISCONNECT message to the client, too.
# Versions
Each protocol buffer message must include a version number. It has a default tag and need to be filled from the default protocol buffer instance: msg->set_version(msg->default_instance().version());
Protocol buffers are backwards compatible, but newer features might not work with an older protocol buffer file version. Those messages are normally ignored and should not cause misbehaviour in your client application.

33
Remote-Control.md Normal file

@ -0,0 +1,33 @@
# Using remote control functions with Clementine
# Introduction
In the latest Clementine release it is possible to control Clementine from a remote device like an Android Phone.
Download Clementine 1.2 here: http://www.clementine-player.org/downloads
# Details
## Activate Remote Control in Clementine
The remote control is disabled by default. You have to active it in the settings first.
Go to the Settings and select the "Network Remote" item.
- Port: You can change the port on which Clementine should listen for incoming connections.
- Accept only private clients: Clementine will accept clients with a private ip only. (10.x.x.x, 172.16.x.x - 172.31.255.255, 192.168.x.x)
- Use authentication code: Clients must enter this code in order to connect to Clementine
## Clementine Remote Android App
You can download the Clementine Remote Android App here: [Google Play Store](https://play.google.com/store/apps/details?id=de.qspool.clementineremote) or on the [Project Website](https://code.google.com/p/clementine-remote-android)
Or just scan the QR-Code with your favourite scanner:
https://clementine-player.googlecode.com/git/data/clementine_remote_qr.png
After you installed the app you can enter the ip-address of your computer to control Clementine. If you don't know it, check the network remote settings, your ip address is shown there. Enter it in the ip address field on Clementine Remote.
If you changed the port you have to change it in the app as well. Just open the settings and enter the port.
With the use of an authentication code Clementine Remote will promt a dialog. There you have to enter the code you specified in the settings in Clementine.

32
Wii-Remotes.md Normal file

@ -0,0 +1,32 @@
# Using your Wii Remote with Clementine
# Introduction
From version 0.5 you can use your [Wii Remote](http://en.wikipedia.org/wiki/Wii_Remote) as a remote control for Clementine.
This guide explains how to install and configure Wiimotedev to let Clementine see your Wii Remote. Your computer will need to be able to use **Bluetooth** - either through a builtin transmitter (eg. in a laptop) or using a USB Bluetooth dongle.
For now this guide only works on **Linux**.
# Details
- Download the [latest stable version of wiimotedev-daemon](http://code.google.com/p/wiimotedev/downloads/list)
- Extract the tarball and compile and install wiimotedev. Swap `ubuntu` below for your distro: either `debian`, `gentoo`, `slackware`, or `ubuntu`.
tar -xvf wiimotedev-daemon-stable_1.2.tar.bz2
cd wiimotedev-wiimotedev-daemon/
cmake . -DDISTRO=ubuntu -DCMAKE_INSTALL_PREFIX=/usr
make
sudo make install
- Start wiimotedev-daemon:
sudo /etc/init.d/wiimotedev-daemon start
- Now you need to find the Bluetooth MAC address of your Wii Remote. Watch the system log file by running:
tail -f /var/log/messages
Now simultaneously press the **1** and **2** buttons on your Wii Remote. You should see a message in the log that looks like:
wiimotedev: wiiremote 00:19:1D:A8:E0:FB is unregistred, disconnected
The number `00:19:1D:A8:E0:FB` is the MAC address of your Wii Remote.
- Open the file `/etc/wiimotedev/wiimotedev.conf` in an editor. You need to add the MAC address that you just discovered to the `[sequence]` section at the bottom of the file, like so:
[sequence]
00:19:1D:A8:E0:FB=1
- Save the file and restart wiimotedev-daemon:
sudo /etc/init.d/wiimotedev-daemon reload
- You should now be able to use your Wii Remote from inside Clementine! Open the Preferences dialog by clicking *Tools* and *Preferences...*, and click on the *Wiimotedev* tab.