Serviio - free DLNA media server for Windows, Mac and Linux

Media Streaming Server

Editing renderer profiles

Serviio includes the possibility to add / edit renderer profiles . This gives the users the means to make Serviio work with their rendering devices (e.g. TV) that is not yet officially supported by the latest release. This little guide should help users to add a new renderer profile ("profile" from now on).

Basics

Profiles definition is stored in file config/profiles.xml in the Serviio installation directory. It is a simple XML file which you can edit in any text editor or even better in a XML editor (where you can facilitate schema validation).

If you want to have your profile changes persisted across upgrades, you can add new profiles to a file config/user-profiles.xml. All the syntax and rules described below apply to this file as well.

The process of getting the changes into effect is following:

  1. edit profiles.xml
  2. restart Serviio server; this means restarting the actual Serviio server process, e.g. Windows service or Linux/OSX process, not just the UPnP server via the console buttons
  3. assign your profile to your device (IP) in the console and Save the setting
The basic structure of profiles.xml is following:


<Profiles>
  <Profile id="[profile_id]" name="[name of profile]" extendsProfileId="[id_of_parent_profile]"
           alwaysEnableTranscoding="[true/false]">
    <ContentDirectoryMessageBuilder/>
    <Detection/>
      <UPnPSearch>
        <FriendlyName>[regex]</FriendlyName>
        <ModelName>[regex]</ModelName>
        <ModelNumber>[regex]</ModelNumber>
        <ProductNumber>[regex]</ProductNumber>
        <Server>[regex]</Server>
        <Manufacturer>[regex]</Manufacturer>
      </UPnPSearch>

      [and/or]

      <HttpHeaders>
         <HTTP_header_name>[regex]</HTTP_header_name>
      </HttpHeaders>
    </Detection>     
    <ProtocolInfo/>     
    <DeviceDescription>       
      <FriendlyName/>       
      <ModelName/>   
      <ModelNumber/>  
      <ExtraElements/>
    </DeviceDescription>     
    <ResourceTransportProtocolHandler/>
    <ContentDirectoryDefinitionFilter/>
    <H264LevelCheck/>
    <MediaFormatProfiles>
       <MediaFormatProfile mime-type="[mime_type]" name="[DLNA_format_profile_name]"/>       

       [... more profiles ...]

    </MediaFormatProfiles>
    <Transcoding>
        <Video targetContainer="[container]" targetVCodec="[video_codec]" targetACodec="[audio_codec]"
               maxVBitrate="[bit_rate]">
            <Matches container="[container]" vCodec="[video_codec]" aCodec="[audio_codec]"/>

            [... more file matches ...]

         </Video>

         <Audio targetContainer="[container]">
            <Matches container="[container]"/>

            [... more file matches ...]

         </Audio>
  
         <Image>
            <Matches container="[container]"/>

            [... more file matches ...]

         </Image>

        [... more transcoding definitions ...]

    </Transcoding>
    <OnlineTranscoding>
        
        [... the same as Transcoding ...]
  
    </OnlineTranscoding>
    <GenericTranscoding>
        <Video> ... </Video>
    </GenericTranscoding>
    <AutomaticImageRotation />
    <LimitImageResolution />
    <Subtitles>
        <SoftSubs mime-type="[mime_type]" type="[srt/vtt]" character-encoding="utf-8"/>
        <HardSubs>
            <BitmapBased supported="true"/>
            <TextBased supported="true">
               <RequiredFor container="*"/>
               [... more RequiredFor ...]
            </TextBased>
        </HardSubs>                  
    </Subtitles>
    <ThumbnailsResolution/>
    <AllowChunkedTransfer forced="true"/>
  </Profile>

  [... more profiles ...]

</Profiles>

In order to add a new profile you'll have to add a new <Profile> block to the file and restart Serviio.

Inheritance

Profiles in Serviio are based on inheritance. It means that Profile B can inherit from Profile A and only change or add certain values. The remaining values will be retained from the parent Profile A. Please note that not all the values are inherited (e.g. transcoding, see below).

Generic Profile (id=1) should be used as a parent for most other profiles. This profile defines values that follow relevant specifications and doesn't include any transcoding definitions for local content. These are the values that are inherited can be "overwritten" in the child profiles:

  • ContentDirectoryMessageBuilder
  • ProtocolInfo
  • DeviceDescription (and all/some of its sub-elements)
  • ResourceTransportProtocolHandler
  • ContentDirectoryDefinitionFilter
  • MediaFormatProfiles
  • H264LevelCheck
  • AutomaticImageRotation
  • LimitImageResolution
  • Subtitles
  • Transcoding (special rules)
  • OnlineTranscoding (special rules)
  • GenericTranscoding
  • ThumbnailsResolution
  • AllowChunkedTransfer

Element description

Profile - includes values of a renderer profile

Attributes:

  • id - ID of the profile, must be a unique value
  • name - name of the profile
  • extendsProfileId - ID of a parent profile in a case the profile has one
  • alwaysEnableTranscoding - if true, it overides any user setting related to turn off transcoding; default is false

ContentDirectoryMessageBuilder - a Java class responsible for generating communication data - don't change this

 

Detection - used to automatically detect the renderer

  • UPnPSearch - detects device by issuing a UPnP M-SEARCH request and (for the devices that support it) matches selected device description fields (see above) using the provided regular expression. This is the preferred method.
  • HttpHeaders - detects device based on HTTP headers in the incoming requests

ProtocolInfo - type of protocol info that will be published to the renderer. Can be:

  • DLNA - should be used for DLNA compliant devices
  • simple - simple UPnp-type protocol info, used by non-DLNA devices like XBox 360

DeviceDescription - defines how Serviio will be identified to the renderer - don't change this

ResourceTransportProtocolHandler - a Java class implementing a specific additional code for handling resource transport; includes manufacturer-specific logic

ContentDirectoryDefinitionFilter - a Java class implementing filter of library definition, needed by some devices

MediaFormatProfiles - defines set of media format profiles (or their changes) the renderer expects. All the format profiles are defined for Generic profile and you should only change those that cause your media files to be unrecognized by your device.

Attributes:

  • mime-type - mime-type to be used as an identified of media files with this format profile
  • name - format profile name to be sent to the device as a part of protocol info (DLNA_PN field), if different from the internal format profile name

H264LevelCheck - type of check for H264 level the device uses. Can be:

  • HEADER - only takes into accunt the level value stored in H264 header
  • FILE_ATTRIBUTES - only takes into account the level computed from the file's characteristics (e.g. number of ref frames)
  • ANY - takes into account both of the above and uses the higher from the two values

Transcoding - defines transcoding configuration for local/online files.

OnlineTranscoding - defines transcoding configuration for online files.

GenericTranscoding - defines transcoding configuration to be used in specific cases, like hard subs encoding and video stacking.

AutomaticImageRotation - If 'true' Serviio will rotate images based on EXIF metadata (where present) so that they are correctly displayed on the screen

LimitImageResolution - If 'true' Serviio will resize images whose resolution is higher than 4096x4096 (specification maximum resolution)

Subtitles - includes definition of subtitles rendering

  • SoftSubs - delivers subtitles to the renderer as an external resource; only some renderers support this
  • HardSubs - encodes the subtitles text or bitmaps into the video stream. It can specify which video containers require this delivery type (the other using soft subs)

ThumbnailsResolution- resolution of the thumbnails to be server to the renderer. Can be:

  • DLNA - standard DLNA thumbnail resolution
  • HD - higher resolution thumbnails if supported by the renderer

AllowChunkedTransfer- if 'true' it will use chunked HTTP transfer for HTTP/1.1 communication where required. If the forced attribute is set to 'true', it will use chunked transfer regardless HTTP version.

Example

This profile is for PS3. It uses user agent for automatic detection and overwrites mime-type for AVI files. The other values are inherited from Generic profile.


<Profile id="4" name="Playstation 3" extendsProfileId="1">
 <Detection>
  <HttpHeaders>
   <X-AV-Client-Info>.*PLAYSTATION 3.*</X-AV-Client-Info>
  </HttpHeaders>
 </Detection>
 <MediaFormatProfiles>
   <MediaFormatProfile mime-type="video/divx">AVI</MediaFormatProfile>
 </MediaFormatProfiles>
</Profile>