Add listen endpoint

2 files changed, 52 insertions, 1 deletions

diff --git a/README.md b/README.md
index 56c264e..dc8b4a0 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,14 @@ funkwhale = Funkwhale(client_name, redirect_uri, client_id, client_secret,
 artists = funkwhale.artists()
 
 print(artists)
+
+# In case you ask, their is an example for downloading a song
+r = funkwhale.listen("f9d02c64-bafa-43cb-8e1e-fa612e7c5dab")
+
+with open('/tmp/test.mp3', 'wb') as f:
+    for chunk in r.iter_content(chunk_size=8192):
+        if chunk:
+            f.write(chunk)
 ```
 
 # Features
@@ -81,7 +89,7 @@ List of features implemented or planned:
   - [x] List tracks
   - [x] Retrieve a single tracks
   - [x] List available user libraries containing work from this track
-- [ ] Download the audio file matching the given track uuid
+- [x] Download the audio file matching the given track uuid
 - [ ] License
   - [ ] List licences
   - [ ] Retrieve a single license
diff --git a/pyfunkwhale/funkwhale.py b/pyfunkwhale/funkwhale.py
index a222174..c892b37 100644
--- a/pyfunkwhale/funkwhale.py
+++ b/pyfunkwhale/funkwhale.py
@@ -267,3 +267,46 @@ class Funkwhale(object):
 
         return self.client.call(
                 f'/tracks/{_id}/libraries/', 'get', params).json()
+
+    def listen(self, _uuid, to: str = None, upload: str = None):
+        """
+        Download the audio file matching the given track uuid
+
+        Given a track uuid (and not ID), return the first found audio file
+        accessible by the user making the request.
+
+        In case of a remote upload, this endpoint will fetch the audio file
+        from the remote and cache it before sending the response.
+
+        Parameters
+        ----------
+        _uuid : str
+            Track uuid
+        to : str, optional
+            If specified, the endpoint will return a transcoded version of the
+            original audio file.
+            Since transcoding happens on the fly, it can significantly
+            increase response time, and it's recommended to request transcoding
+            only for files that are not playable by the client.
+            This endpoint support bytess-range requests.
+            Available values : ogg, mp3
+        upload: str, optional
+            If specified, will return the audio for the given upload uuid.
+            This is useful for tracks that have multiple uploads available.
+
+        Raises
+        ------
+        ValueError
+            If `to` are set with wrong values
+        """
+
+        arguments = locals()
+
+        to_fields = ['ogg', 'mp3']
+        if to is not None and to not in to_fields:
+            raise ValueError("The to field {} is not in the to"
+                             "fields accepted".format(to))
+
+        params = self._build_params(arguments)
+
+        return self.client.call(f'/listen/{_uuid}', 'get', params)