Encoder Plug-in SDK

From JRiverWiki
Jump to: navigation, search

This is preliminary documentation and subject to change.

This SDK contains everything you need to create an encoder plug-in for Media Center. A Media Center encoder plug-in is a COM control which has two modes of operation. One mode takes a wave format filename and encodes that to a given output filename. The other mode takes buffers in memory and encodes them to the given output filename. There are three COM interfaces, a general interface which handles some housekeeping and the first operation mode (file to file), an extended interface which handles the "on-the-fly" memory buffer encoding, and an event interface which relays information back to the calling application.

Writing a plug-in

The best way to learn about Media Center's plug-in architecture, and to eventually create your own plug-in, is to start with the example provided. The example (project "MyEncoder") creates a Media Center encoder plug-in called "Reverse" which simply reverses the wave data fed to it, so you end up with a track that plays backwards. You should be able to simply make changes where necessary to this project and end up with a plug-in which actually does something useful, such as encode wave data to your own format.

Some Considerations

Here are just a few things to remember when writing a plug-in:

  • The example plug-in was made with Microsoft Visual Studio .NET v7.
  • The plug-in will be a DLL file which when registering must create the proper entries in the Media Center encoder section of the system registry. The examples show how to do this.
  • The simplest way to create a new plug-in is to copy and modify the example provided (MyEncoder). However, you must remember to create new unique GUID's and replace the ones included in the project. You can create new GUIDS with the guidgen.exe program provided with Visual C++, then replace the old ones in the sample project's IDL and RGS files and rebuild the project.

Steps for creating the plug-in

  1. Copy the included example project "MyEncoder" to a project directory.
  2. Edit the IDL file (myencoder.idl) replacing all "uuid" entries with new ones created by the guidgen.exe program. Do a "build".
  3. Edit the RGS file (MyImpl.rgs) replacing the "CLSID" instances with your new CLSID which can be found in the "MyEncoder_i.c" file as CLSID_MyImpl. Make sure you did the build after editing the IDL file before editing the RGS file, as the IDL compiler creates the MyEncoder_i.c file. Also replace the CLSID on the line that starts with "ForceRemove". Do another build.
  4. Edit the DllRegisterServer function in the MyEncoder.cpp file to reflect your own encoder's information. The main things to modify are RegistryPath, strCompany, strVersion, strURL, strCopyright, and strExt. Also set the MY_EXTENSION define to the file extension needed for your encoder (such as "mp3", or "ape"). Comments in this file will tell you the meanings of the important variables. The registry key you set up in the RegistryPath variable will be the name of the encoder as the user sees it in Media Center.
  5. Now the guts of the encoding process take place in MyImpl.cpp. This is where you take the wave data, convert it to your format, then write it out. The functions that do most of the work are: Start, Stop, InitBufferInput, EncodeBuffer, FinishBufferInput, and Options if you need an options dialog. Take a look at the provided sample code to help you figure out how to implement these functions.

The GetInfo Function

The GetInfo function is a generic method for passing information back from an encoder. It takes a string argument and returns a string value:

  • Bitrate: asks for an estimate of the bitrate. For example, the Ape encoder returns the string "750".
  • RipAndEncode: asks whether the encoder can have two instances running at the same time. Should return "Yes" or "No".

Support

If you have questions or concerns not addressed by this SDK, or just have suggestions for making the SDK more understandable, please visit our Developer's Zone or Interact