Restructured for future expansion of the SCDL module(s)

.gitignore

@@ -0,0 +1,8 @@
+# Compiled Source
+.pyc
+
+# OS Junk
+.DS_Store
+
+
+

License.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Joe Engelman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

manifest.in

@@ -0,0 +1 @@
+include requirements.txt

scdl.py

@@ -12,7 +12,7 @@
 from mutagen.mp3 import MP3
 from mutagen.id3 import ID3, APIC, error
 
-CLIENT_ID = '49009eb8904b11a2a5d2c6bdc162dd32'
+CLIENT_ID = '49009eb8904b11a2a5d2c6bdc162dd32'	# feel free to replace this with your own client ID
 MEDIA_STREAM_URL = 'http://media.soundcloud.com/stream/'
 
 # color codes for terminal output

scdl/init.py

@@ -0,0 +1 @@
+# deliberately left empty (for now)

scdl/scdl.py

@@ -0,0 +1,154 @@
+#! /usr/bin/env python
+
+# usage : python scdl.py <soundcloud track/playlist url>
+
+import soundcloud
+import urllib
+import re
+import time
+import os
+import sys
+
+from mutagen.mp3 import MP3
+from mutagen.id3 import ID3, APIC, error
+
+CLIENT_ID = '49009eb8904b11a2a5d2c6bdc162dd32'
+MEDIA_STREAM_URL = 'http://media.soundcloud.com/stream/'
+
+# color codes for terminal output
+class colors:
+    HEADER = '\033[95m'
+    OKBLUE = '\033[94m'
+    OKGREEN = '\033[92m'
+    WARNING = '\033[93m'
+    FAIL = '\033[91m'
+    END = '\033[0m'
+
+class scdl:
+	client = soundcloud.Client(client_id=CLIENT_ID)
+
+	def __init__(self, url, download_path, silent=True):
+		self.url = url
+		self.download_progress = 0
+		self.download_path = os.path.expanduser(download_path)
+		self.current_time = time.time()
+		self.track_url_dicts = self.resolve(url)
+		self.silent = silent
+
+	# resolve a Soundcloud URL 
+	# return track details in list (i.e. if only a single song, 
+	#	a single element list will be returned)
+	def resolve(self, url):
+		returnMedia = []
+		resolved_url = self.client.get('/resolve', url=url);
+		if resolved_url.kind == 'track':
+			# resolved_url is a single track object 
+			returnMedia.append(self.get_track_detail(resolved_url.id))	
+		elif resolved_url.kind == 'playlist':
+			# resolve_url is a list of song objects
+			for track in resolved_url.tracks:
+				returnMedia.append(self.get_track_detail(track['id']))
+		elif resolved_url.kind == 'user':
+			track_list_url = 'https://api.soundcloud.com/users/' + str(resolved_url.id) + '/tracks'
+			tracks = self.client.get(track_list_url)
+			for track in tracks:
+				returnMedia.append(self.get_track_detail(track.id))
+		return returnMedia
+
+ 	# return a dict of important attributes for a specific track
+	def get_track_detail(self, track_id):
+		regex = re.compile('\/([a-zA-Z0-9]+)_')
+		track = self.client.get('/tracks/' + str(track_id))
+		track_detail = {'title':track.title,
+						# keep a version of the title that can be used as a filename
+						'artist':re.sub('[\/:*?"<>|%]', '-', track.user['username']),
+						'safe_title':re.sub('[\/:*?"<>|%]', '-', track.title),
+						# find the streaming URL for this track
+					 	'stream_url':MEDIA_STREAM_URL + str(regex.search(track.waveform_url).groups()[0]),
+					 	# find this track's artwork URL (or substitute with the user's avatar URL)
+					 	'artwork_url':(track.artwork_url if track.artwork_url else track.user['avatar_url'])}
+		return track_detail
+
+	# iterate through a list of track detail dicts and download each one
+	# return a list of filenames where the tracks were downloaded to
+	def dl_tracks(self, tracks):
+		track_filename_list = []
+		for track in tracks:
+			try:
+				# create a folder to store this artist's tracks
+				artist_folder = self.download_path + track['artist'] + '/'
+				if not os.path.isdir(artist_folder):
+					os.mkdir(artist_folder)
+				track_filename = artist_folder + "{0}.mp3".format(track['safe_title'])
+				artwork_filename = artist_folder + ".{0}-artwork.jpg".format(track['safe_title'])
+				if not self.silent: 
+					sys.stdout.write(colors.HEADER + "Downloading: " + colors.END + colors.OKBLUE + "{0}".format(track['title']) + colors.END + "\n")
+				urllib.urlretrieve(url=track['stream_url'], filename=track_filename, reporthook=(None if self.silent else self.dl_progress))
+				# reset variables so next track's report hook doesn't malfunction
+				self.download_progress = 0
+				self.current_time = time.time()
+				if not self.silent: 
+					print
+				# get the track's artwork
+				urllib.urlretrieve(url=track['artwork_url'], filename=artwork_filename)
+				embed_artwork(track_filename, artwork_filename)
+				os.remove(artwork_filename)
+				track_filename_list.append(track_filename)
+			except:
+				# in case of failure, just move on to next track
+				continue
+		return track_filename_list
+
+	# a basic report hook that monitors a download's progress
+	def dl_progress(self, block_no, block_size, file_size):
+		self.download_progress += block_size
+		if int(self.download_progress / 1024 * 8) > 1000:
+			speed = "{0:7.2f} Mbps".format(round((self.download_progress / 1024 / 1024 * 8) / (time.time() - self.current_time), 2))
+		else:
+			speed = "{0:7.2f} Kbps".format(round((self.download_progress / 1024 * 8) / (time.time() - self.current_time), 2))
+		rProgress = round(self.download_progress / 1024.00 / 1024.00, 2)
+		rFile = round(file_size / 1024.00 / 1024.00, 2)
+		percent = round(100 * float(self.download_progress) / float(file_size))
+		percent = min(percent, 100)
+		sys.stdout.write("\r" + colors.OKGREEN + "{3} ({0:.2f}/{1:.2f}MB): {2:6.2f}%".format(rProgress, rFile, percent, speed) + colors.END)
+		sys.stdout.flush()
+
+# takes a track's filename and it's artwork's filename and uses ID3 to embed
+# 	the artwork within the track file
+def embed_artwork(track_filename, artwork_filename):
+	audio = MP3(track_filename, ID3=ID3)
+	# add ID3 tag if it doesn't exist
+	try:
+	    audio.add_tags()
+	except error:
+	    pass
+	audio.tags.add(
+	    APIC(
+	        encoding=3, # 3 is for utf-8
+	        mime='image/jpg', # image/jpeg or image/png
+	        type=3, # 3 is for the cover image
+	        desc=u'Cover',
+	        data=open(artwork_filename).read()
+	    )
+	)
+	audio.save()
+
+# easy download method to download a track specified by 'url' to a folder 'download_path'
+# returns a list of full filenames and paths of downloaded tracks
+def download(url, download_path, silent=True):
+	skipper = scdl(url, download_path, silent)
+	track_urls = skipper.track_url_dicts
+	return skipper.dl_tracks(track_urls)
+
+if __name__ == "__main__":
+	dest = os.path.expanduser('~/Music/Soundcloud/')
+	list_of_downloaded_filenames = []
+	for i in range(1, len(sys.argv)):
+		link = sys.argv[i]
+		list_of_downloaded_filenames += download(link, dest, silent=False)
+	print
+	print colors.HEADER + "The following files were downloaded successfully:" + colors.END
+	for i, filename in enumerate(list_of_downloaded_filenames):
+		print "\t" + colors.HEADER + str(i+1) + ". " + colors.END + colors.OKBLUE + " {0}".format(filename[len(dest):].split('/')[1]) + colors.END
+	print colors.OKGREEN + "Finished." + colors.END
+

setup.py

@@ -0,0 +1,47 @@
+from distutils.core import setup
+
+setup(
+    name = 'scdl',
+    packages = ['scdl'],
+    version = '0.1.0',
+    description = 'Simple Soundcloud Downloader',
+    author='Joe Engelman',
+    author_email = "[email protected]",
+    url = "https://github.com/joengelm/scdl",
+    download_url = "https://github.com/joengelm/scdl/archive/v0.1.0.zip",
+    keywords = ["soundcloud", "download", "music", "streaming", "simple"],
+    classifiers = [
+        "Programming Language :: Python",
+        "License :: OSI Approved :: MIT License",
+        "Development Status :: 4 - Beta",
+        "Operating System :: OS Independent",
+        ],
+    long_description = """\
+SCDL: A simple, yet powerful Soundcloud Downloader
+--------------------------------------------------
+
+What?
+SCDL is a basic library for downloading tracks and playlists from Soundcloud. With one call to 'scdl.download', you can easily save a track or playlist to your computer. SCDL also provides informative output about a song's download progress and embeds each track's artwork into its mp3 file. By default, SCDL will download tracks into the user's '~/Music/Soundcloud/artist/' folder, where artist is the owner of the track (not necessarily the actual artist of the song).
+
+Why?
+SCDL provides a jumping off point which is simple enough for nearly all programmers to understand. Anyone can create a Python script that uses SCDL to augment their applications or to create entirely new Soundcloud apps.
+
+Example:
+
+    from scdl import download
+    url = 'https://soundcloud.com/joeengelman/lion-king-for-drum-corps'
+    dest = './Soundcloud/'
+    download(url, dest, silent=False) # The silent argument is optional and, if true, disables progress output
+    # That's it! You've just downloaded a song from Soundcloud.
+
+You can also use scdl.py with command line arguments:
+
+    python scdl.py 'https://soundcloud.com/joeengelman'
+    python scdl.py 'https://soundcloud.com/joeengelman/lion-king-for-drum-corps'
+    python scdl.py 'https://soundcloud.com/joeengelman/sets/winter-2015'
+
+Note: scdl.py can handle an arbitrary number of arguments, and it will download each one in turn.
+
+This version requires Python 2.x. It has not been tested with Python 3.
+"""
+)