Extend doubleTwist and sync to any device

Extending doubleTwist's device support

Overview

doubleTwist enables developers to customize the way in which it interacts with devices. Most of the knowledge about a device is declared in an external XML file. These external XML files are called device adapaters and allow customization of device identification, the folders to which media is synced, folders to search when browsing media, decoder capabilities, and encoder settings.

A "catch-all" device adapter exists to provide base support for any device that isn't explicitly identified and customized by other device adapters. It is limited to audio and image support and defines the following behavior:

The entire file system of the largest storage card is searched for media when browsing the device in doubleTwist.
MP3 files can by synced to the device without incurring a transcode (bitrate: 20 - 320 kbps, 1 or 2 channels).
Audio files that require transcoding will be transcoded to MP3 at 128 kbps, 2 channels.
Video is not supported.

Note that not all interaction with a device is customizable. Most notably, the way in which playlists are written to a device is something that cannot be changed. The storage card used in the sync process also cannot be customized: the card with the largest capacity is used.

Benefits

The primary reason to create a new device adapter is to add video support for a device. Unlike audio, there is no industry standard video encoding for portable media devices today. Resolution capabilities can also vary greatly from device to device. For this reason, the catch-all device adapter does not provide support for video. Creating a device adapter for a specific device or class of devices can enable doubleTwist to sync video accordingly.

Another reason to create a device adapter is to realize gains in browsing efficiency, sync efficiency, and media quality. For example, rather than searching a device's entire file system for media when browsing, a set of sub-folders can be specified to limit the search. When syncing media to a device, if the device is known to support formats other than mp3, alternative decoders can be specified to avoid unnecessary transcoding. Lastly, alternative encode settings can be specified to transcode media into a format better suited for a particular device.

Distribution

On Windows, doubleTwist looks for 3rd party device adapters in the following folders:
WinXP: C:\Documents and Settings\All Users\doubleTwist Corporation\doubleTwist desktop\Adapters
Vista/W7: C:\Users\All Users\doubleTwist Corporation\doubleTwist desktop\Adapters

On Mac OS X, doubleTwist looks for 3rd party device adapters in the folder
~/Library/Application Support/doubleTwist/Adapters.

Any file in these folders with an extension of ".xml" will be parsed as a device adapter. If there are user-generated device adapters that conflict with doubleTwist's adapters for a given device then the user-generated ones will take precedence.

Implementation

Have a look at the adapter XML schema documentation and download the adapter editor tool (updated, version 1.1!) for Windows.

If you have any questions regarding device adapters, feel free to ask in our forums or send an email to adapters@doubletwist.com.

Example

<?xml version="1.0"?>
<Adapter xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Guid>DFB806EC-3843-4f24-95C7-C5E83988C249</Guid>
  <Type>Phone</Type>
  <Manufacturer>Acme</Manufacturer>
  <Model>A100</Model>
  <Name>Acme Prime</Name>
  <Version>1</Version>
  <IsClass>false</IsClass>
  <Identifiers>
    <Identifier>
      <UsbVid>1234</UsbVid>
      <UsbPid>5678</UsbPid>
    </Identifier>
  </Identifiers>
  <MusicFolder>/music</MusicFolder>
  <ImageFolder>/pictures</ImageFolder>
  <VideoFolder>/video</VideoFolder>
  <SearchWhitelist>
    <FolderPath>/DCIM</FolderPath>
  </SearchWhitelist>
  <AudioDecoders>
    <AudioDecoder>
      <FileFormats>
        <FileFormat>Mp4</FileFormat>
      </FileFormats>
      <Audio>
        <Encodings>
          <AudioEncoding>Aac</AudioEncoding>
        </Encodings>
        <Channels>
          <Value>1</Value>
          <Value>2</Value>
        </Channels>
      </Audio>
    </AudioDecoder>
    <AudioDecoder>
      <FileFormats>
        <FileFormat>Mpg</FileFormat>
      </FileFormats>
      <Audio>
        <Encodings>
          <AudioEncoding>Mp3</AudioEncoding>
        </Encodings>
        <Channels>
          <Value>1</Value>
          <Value>2</Value>
        </Channels>
      </Audio>
    </AudioDecoder>
    <AudioDecoder>
      <FileFormats>
        <FileFormat>Wav</FileFormat>
      </FileFormats>
      <Audio>
        <Encodings>
          <AudioEncoding>Pcm</AudioEncoding>
        </Encodings>
        <Channels>
          <Value>1</Value>
          <Value>2</Value>
        </Channels>
      </Audio>
    </AudioDecoder>
  </AudioDecoders>
  <VideoDecoders>
    <VideoDecoder>
      <FileFormats>
        <FileFormat>Mp4</FileFormat>
      </FileFormats>
      <Video>
        <Encodings>
          <VideoEncoding>Mp4</VideoEncoding>
        </Encodings>
        <Widths Min="1" Max="480" />
        <Heights Min="1" Max="320" />
        <Bitrates Min="1" Max="2000000" />
        <Profiles>
          <Value>0</Value>
        </Profiles>
        <Levels>
          <Value>0</Value>
          <Value>1</Value>
        </Levels>
        <FrameRates Min="29.97" Max="29.97" />
      </Video>
      <Audio>
        <Encodings>
          <AudioEncoding>Aac</AudioEncoding>
        </Encodings>
        <Bitrates Min="1" Max="512000" />
        <SampleRates Min="1" Max="48000" />
        <Channels>
          <Value>1</Value>
          <Value>2</Value>
        </Channels>
      </Audio>
    </VideoDecoder>
  </VideoDecoders>
  <ImageDecoders>
    <ImageDecoder>
      <Image>
        <Encodings>
          <ImageEncoding>Jpg</ImageEncoding>
          <ImageEncoding>Gif</ImageEncoding>
          <ImageEncoding>Png</ImageEncoding>
        </Encodings>
        <Widths Min="1" Max="480" />
        <Heights Min="1" Max="320" />
      </Image>
    </ImageDecoder>
  </ImageDecoders>
  <EncodeProfiles>
    <EncodeProfile xsi:type="VideoEncodeProfile">
      <Id>F003BF12-4EB7-421c-9B46-F56AEEF59504</Id>
      <FileFormat>Mp4</FileFormat>
      <VideoSettings>
        <Encoding>Mp4</Encoding>
        <Width>480</Width>
        <Height>320</Height>
        <Bitrate>
          <Default>1200000</Default>
        </Bitrate>
        <FrameRate>29.97003</FrameRate>
      </VideoSettings>
      <AudioSettings>
        <Encoding>Aac</Encoding>
        <Bitrate>
          <Default>128000</Default>
        </Bitrate>
        <SampleRate>48000</SampleRate>
        <Channels>2</Channels>
      </AudioSettings>
    </EncodeProfile>
    <EncodeProfile xsi:type="AudioEncodeProfile">
      <Id>274EC821-8A62-4f7b-85AD-B2DD861E7835</Id>
      <FileFormat>Mp4</FileFormat>
      <AudioSettings>
        <Encoding>Aac</Encoding>
        <Bitrate>
          <Default>128000</Default>
        </Bitrate>
        <SampleRate>44100</SampleRate>
        <Channels>2</Channels>
      </AudioSettings>
    </EncodeProfile>
    <EncodeProfile xsi:type="ImageEncodeProfile">
      <Id>5332C22B-AFCA-48b9-9175-3E38B02A371F</Id>
      <ImageSettings>
        <Encoding>Jpg</Encoding>
        <Width>480</Width>
        <Height>320</Height>
      </ImageSettings>
    </EncodeProfile>
  </EncodeProfiles>
  <DefaultAudioEncodeProfile>274EC821-8A62-4f7b-85AD-B2DD861E7835</DefaultAudioEncodeProfile>
  <DefaultVideoEncodeProfile>F003BF12-4EB7-421c-9B46-F56AEEF59504</DefaultVideoEncodeProfile>
  <DefaultImageEncodeProfile>5332C22B-AFCA-48b9-9175-3E38B02A371F</DefaultImageEncodeProfile>
</Adapter>