Sunday 28 August 2011

How To: Create Extensions for Smooth YouTube Downloader


Overview:
This page is for Developers who would like to create an Extension for Smooth YouTube Downloader, to support Searching and Downloading from Sites other than YouTube


Warning: Sites which contain adult content will not be supported nor included in the application !


How To:
The way extensions work is very straight forward, all you need to do is Create a class which Implements an Interface with few functions, then copy the resulting assembly to "Extensions" folder in "\Program Files\SmoothYTDownloader\Extensions" directory on device along (for a normal default installation) with the XML that defines the FileName of the assembly along with the Class FullName.


Stary by downloading this sample project, which contains The Source Code for "DailyMotion" Extension


Now I'll explain each method in the Interface and when it's called:


public interface IDownloadService
    {
        string DeveloperNotes { get; }
        string Name { get; }
        int SearchItemHeight { get; }
        int SearchItemSelectedHeight { get; }
        List<VideoFormat> GetAvailableFormats(VideoInfo videoInfo);
        string GetUniqueName(VideoInfo videoInfo);
        string GetVideoUrl(VideoInfo videoInfo);
        void OnFormatSelected(VideoInfo videoInfo, VideoFormat selectedFormat);
        List<VideoInfo> Search(string searchText, int currentPage, int maxResult);
    }


  • string DeveloperNotes { get; }

This will be displayed for users, when they click on "Show Developer Notes" in the "Download Service" selection screen, just in case there are some special cases in your Extension.





  • string Name { get; }
Name of Download Service, which will be Displayed in the "Download Service" selection screen
  • int SearchItemHeight { get; }
Normal item height in Search screen, this value usually depends on the height of thumbnails for the site.
  • int SearchItemSelectedHeight { get; }
Height of search item on selection, which will also Display the Duration of the video, so make sure to leave a space for that below the Thumbnail image.

  • List<VideoInfo> Search(string searchText, int currentPage, int maxResult);
This is the first main function, it's called when a user enters text in the search screen box, and hits Search.
It returns a list of VideoInfo objects, which will be passed later to other functions.
VideoInfo class can be found in the WassimK.Utils assembly, found in the sample project along with the Interface to implement.
For this function, you need to provide values for:
VideoInfo.Title // Title to be displayed in Search results
VideoInfo.Duration // Video Duration
videoInfo.ImageUrls // Urls for Thumbnails

And you can also save some values using:
VideoInfo["Key"] = "Value";
Usually you need to store video ID in this stage.

Parameters:
  1. currentPage: This value starts with 1 and is incremented every time the user hits, "Show More..." in search results, so the Search function should return the next set of Search Results depending on this value.
  2. maxResult: Maximum number of search results per search page.


  • List<VideoFormat> GetAvailableFormats(VideoInfo videoInfo);
This function is called when a user selects an item from Search Results.
videoInfo is the same object returned previously from the Search function above.
Depending on information stored in videoInfo object, you should be able to return a list of formats/qualities supported by selected video.
VideoFormat class has 3 properties that need to be set:
  1. ItemText: Text to Display in the list of Formats screen
  2. Value: Any hidden value developer decides to save and use later to help get the video URL.
  3. Url: This URL is only used to support "Copy Url" functionality, if left empty, the user will see a messagebox saying, "this video doesn't support copy url"
Bear in mind that this videoFormat object will be passed later to the OnFormatSelected function, to help get the correct video Url.


  • void OnFormatSelected(VideoInfo videoInfo, VideoFormat selectedFormat);
This function is called when the user select a format from the Formats Selection Screen.
selectedFormat object contains information saved previously in the GetAvailableFormats function.
Usually in this function, you need to store information in the videoInfo object, which will be passed later to GetVideoUrl function.
The information you need to save is the what will help you get the video url for the selected format.
  • string GetVideoUrl(VideoInfo videoInfo);
This function is called in two situations, when a user selects a format for the list of formats, or the application needs to continue a previously paused Download.
To resume downloads, VideoInfo object is serialized on application exit, and deserialized when the application is launched again, the object is then passed to this function to get the video url and continue downloading.
Important Note: Never store the URL in the videoInfo object, because most of sites copy the video to a cache server and sometimes this cache is cleaned up and the URL is not available anymore, always use the video ID along with other information, like Video format saved in the videoInfo object to get the video Url
  • string GetUniqueName(VideoInfo videoInfo);
This function is called whenever a user select a format from the format screen, it checks if a download of this particular video and format is in progress already. Usually, (videoInfo["ID"] + videoInfo["Format"]) is unique enough for each video.
XML file:
To be able to add your extension to the "Download Services" page you must include both the assembly and an XML file that defines the Download Service to the Root of Extensions folder

The format if the XML file is as follows:
<Service>
  <Assembly FileName="WassimK.DailyMotionService.dll" />
  <Class FullName="WassimK.SmoothYouTubeDownloader.Services.DailyMotionService" />
</Service>
It's straight forward, just one note Class FullName is the "NameSpace.ClassName"
Finally:
This was a very fast explanation and it's a bit ugly to be honest, but I hope it helps some of you, I believe the sample project code should cover most things in detail, if you have any questions or suggestions to improve the API, don't hesitate to write a comment here.

If you'd like your extension to be tested and included in next release, please email it to me, wassim.khalil9@gmail.com

1 comment: