1Soundcloud Browser
2==================
3
4*From v3.7*
5
6Overview
7--------
8
9This browser lets you interact with `Soundcloud <https://soundcloud.com>`_
10and play tracks from the millions on offer.
11Where possible it aims to keep the look and feel as familiar and integrated to
12the Quod Libet experience as possible.
13
14
15.. image:: ../../images/soundcloud-browser-2017-08.png
16    :scale: 50%
17    :align: right
18
19
20Connecting your account
21-----------------------
22If you have a Soundcloud account, you can also:
23
24 * access your favorites
25 * rate (like / unlike) songs.
26 * list your own tracks (QL 3.10+)
27
28To do so, click the Soundcloud connect button at the bottom right.
29
30This will then take you to. If your operating system is configured to process
31``quodlibet://`` URLs with Quod Libet (see `the instructions <https://quodlibet.github.io/callbacks/soundcloud.html?code=CODE_GOES_HERE>`_ given to you there) then
32this process will happen automatically.
33If not, you can enter the code manually using the same button.
34
35If not, you can copy the code from the web page that appears and click the QL button again to enter it.
36
37Once you are logged, in you can log out by clicking the same button again,
38now a disconnect button (seen in the screenshot).
39
40
41Features
42--------
43
44Higher quality streams
45^^^^^^^^^^^^^^^^^^^^^^
46
47The Soundcloud browser will use the download URL, where available, for the highest quality stream.
48Note this may require that you are logged in, and is usually *not* available.
49
50Support for Quod Libet queries
51^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
52
53One of the more interesting features of the soundcloud browser is that it can
54*translate* simpler queries in standard QL syntax to something that can work
55across the web to a library that isn't yours.
56
57Obviously, there are many limitations to this approach both conceptually and
58due to its implementation, but nonetheless queries like ``&(#(length>300), title=dubstep)``
59get (roughly) what you might expect.
60
61
62Favorites
63^^^^^^^^^
64
65These are supported as ``~rating`` (see below), and unrating a track
66will unfavorite it in Soundcloud, if you are logged in.
67
68
69Tags
70^^^^
71
72Supported tags
73 * ``artist``, ``genre``, and ``title`` translate as you might imagine
74 * ``website`` translates to Soundcloud's current URL for that track
75 * ``genre`` holds the genres (plural) tagged in Soundcloud (these are rarely useful but YMMV)
76 * ``date`` is the *creation* date in Soundcloud
77 * ``~#rating`` is translated to 0.0 (not a Soundcloud favourite) or 1.0 (a Soundcloud favourite)
78 * ``~#bitrate`` is the highest bitrate available when playing the track (normally 128)
79 * ``~comments`` translates to the track details in Soundcloud.
80 * ``bpm`` is the Soundcloud BPM if provided.
81
82New tags
83 * ``~#favoritings_count`` and ``~#likes_count`` etc represent how often these tracks have been favorited / liked
84   (note that there currently seem to be inconsistencies within Soundcloud itself as to how these are populated)
85 * ``soundcloud_track_id`` is the Soundcloud ID for the track.
86 * ``soundcloud_user_id`` is the Soundcloud ID for the user.
87 * ``artwork_url`` is the (remote) image URL for the track artwork on Soundcloud.
88   This works well with the corresponding ``Artwork URL Cover Source`` plugin.
89
90
91Comments
92^^^^^^^^
93Comments in Soundcloud have been integrated to QL as read-only bookmarks, as
94they are also time-specific text to do with a particular song. Unlike bookmarks
95they have a lot more metadata (notably the user), so this is rendered as text.
96
97To see them, access as you normally would bookmarks (e.g. view info, right-click the time widget or edit the bookmarks).
98