PySubBox is a utility --more specifically, a Python script-- for
searching, downloading and watching your YouTube subscriptions without 
visiting YouTube it self.

DEPENDANCIES:
	
	* python (tested only under 2.6)
	* python-gdata
	* clive[1] 			- for downloading videos from youtube

RECCOMENDATIONS:

	* mplayer 			- for video playback
	
	MPlayer[2] are no longer 'required' for using PySubBox. However they
	will be used by default.

TERMINOLOGY:	

	"local index" - a directory contianing various sub-directories used
					for containing "media" and "meta" files.

USAGE:

	python subbox.py (update|search|(download|play videoID, ...)) [options]
	
		--index-dir can be used to specify which local index to use.
		Defaults to ~/Videos/Subscriptions
	
		update
		
			Fetches the specified user's subscription feed and updates
			a local index with newly uploaded videos.
			
			Requires -u|--username , -p|--password and --limit options
			to be set.
			
			--limit determines the number of videos to fetch from each
			channel feed. Defaults to 25.
			
			An optional --start-index can also be set to an integer
			value which will indicate which video to start from. 1, the
			default, is the most recently uploaded. Useful if you want
			to backdate your index; just set an arbiturary largish 
			number.
			
		search
		
			Searches the local index against a given query. The video
			title, category and tags are all taken into account. Returns
			a serious of lines in the format
			
				" - VIDEO_ID [*] VIDEO_TITLE"
				
			indicating those that matched the query. The conditional
			asterick signifies whether there is a media file associated
			with the video entry. i.e. whether it's been downloaded yet.
			
			Requires -q|--query to be set. Set to "" to list entire
			index.
			
			The search can be customised by setting the --limit and/or
			--threshold options.
			
				--limit truncates the number of results returned to the
				value provided. e.g. --limit=5 shows only the best five
				results. Defaults to 15.
				
				--threshold sets the 'strictness' of the search relative
				to the 'best match' result. As in, the higher the value,
				theoretically, the less results that match the query.
				
				Should be a value in the range 0 to 1.
				
		download
		
			Downloads the actual video file from YouTube.
			
			An optional --resolution option can be set to a string in 
			the format "width x height" (No spaces or quotation marks.)
			which is transformed into a clive "format" argument. If
			there is no exact match between the given resolution and
			a valid clive format argument, a best match will be used.
			Clive format arguments may be given instead of a resolution.
			
			If multiple video IDs are specified, they'll be downloaded
			concurrently.
			
		play
		
			Plays back a video file.
			
			If multiple video IDs are specified, they'll be played
			sequencially.

FILES:

	~/.config/pysubbox/config.json
	
		A JSON files specifying various configuration options.
		
		Name			Type	Description
		----------------------------------------------------------------
		username		String 	The username you use to login to YouTube. Is
								overiden by -u and --username. No default.
							
		cmd >
		  download		String 	The command used to download the media file.
								Overiden by -c and --cmd. Default:
							
									clive -f {format} --output-file='{media_file}' {uri}
							
		  play			String	The command used to play the media file.
								Overiden by -c and --cmd. Default:
							
									mplayer {media_file}
		
			These commands make use of Python, PEP 3101 string formatting
			to insert metadata about the video. For a comprehensive
			guide to using string formatting, consult the appropriate
			Python documentation.
				
				String			Substitued with ...
				--------------------------------------------------------
				{media_file}	The absolute path to the media file
								associated with the video entry.
								
				{directory}		The absolute path to the directory
								containing the media and meta files.
								
				{title}
				
				{description}
				
				{category}
				
				{uri}			The URI to the watch page of the video.
				
				{id}			The video ID of the video.
				
				{format}		See the FORMAT section of the clive manual.
		
		resolution		String	Supplies the {format} argument when executing
								the download or play commands. Overiden
								by -r and --resolution. Default: best
							
		search_limit	Int		The maximum number of results to return
								when seraching the video index. If 0,
								all matching results will be displayed.
								Overiden by --limit. Default: 15
								
		feed_limit		Int		The number of video enteries to fetch
								from each feed request. Should be in the
								range 0 to 50. Overiden by --limit.
								Default: 25.
								
		threshold		Float	When searching the video index, specifies
								the 'strictness' of the search. Overiden:
								by --threshold. Default: 0.33
								
		index_dir		String	The path to the root of the video index.
								Overiden by --index_dir. Default:
								
									~/Videos/Subscriptions
	
LINKS:

	[1] http://clive.sourceforge.com/
	[2] http://www.mplayerhq.hu/