Understanding the configuration file

I am new to CasparCG. I built my first server 2 years ago, but only used it for playout at one event.
My Server (CASPARCG_SERVER: HP Z400, 3.4Mhz, 12 GBs Ram, Windows 7 Pro, 2 drives- SSD System & Media Drive, Nvidia Quadro 2000, Blackmagic Design Decklink HD Extreme 3 & MiniMonitor 4K, Clean install.
I am running Server 2.0.7 & Client 2.0.8

My system is working!!! I am able to output video on the MiniMonitor and play templates out on the Decklink HD Extreme 3. The reason for this post is although I was able to get things going by copying information, I found on this forum, there are quite a few things I don’t understand. I am looking for a better understanding of how the configuration file works.

I have a couple of questions about how to correctly modify the config file.
I am trying to understand the difference between the two locations that channel is referenced in the config file. One within the initial “Configuration” section and secondly there is the “Channel” section. I am trying to understand how the two relate to each other and/or more importantly how to set them correctly. After some additional reading, I have found a comment that says you determine your video standard in the first config section. If that is the case what should be entered in the “Channel section”?

By default, my config file had “PAL” in the screen consumer. Since I am in the USA, I changed it to NTSC, but then my 720p file played back square. So I modified this setting to 720p2398 and it played out correctly in widescreen format. Then you get down to the “Channel section and again in the “video-mode” section, it had “PAL” which I again changed NTSC (USA) and left the other settings in this section at their default settings. Again after some additional reading, I am questioning what should be entered in this section. Should it be left with the default setting or should I enter by video standard (1080p5994) in this section also?
Do you select your format in the Config section or in the video-mode section? I don’t understand these settings.

Please see the following example below:
NTSC [NTSC|PAL| 576p2500|720p2398|720p2500|720p2400|720p5000|720p2997|720p5994|720p3000|720p6000|1080p2398|1080p2400|1080i5000|1080i5994|1080i6000|1080p2500|1080p2997|1080p3000|1080p5000|1080p5994|1080p6000|1556p2398|1556p2400|1556p2500|dci1080p2398|dci1080p2400|dci1080p2500|2160p2398|2160p2400|2160p2500|2160p2997|2160p3000|dci2160p2398|dci2160p2400|dci2160p2500]

The way I read this is, where “NTSC” is the default, from the [NTSC|PAL| options. With the various resolutions available for playback?

I need to understand how this works. I see this syntax in a couple of other sections, where I would guess the first value (out of brackets) is the default.

<embedded-audio>**true** [true|false]</embedded-audio>
<separate-key>**false** [true|false]</separate-key>

As I’ve searched the forum, I’ve found other examples of config files that include instructions that are not in the original config file. If someone could shed some light on these lines, I would truly appreciate it.
<custom-allocator>true</custom-allocator>
<lock-clear-phrase>secret</lock-clear-phrase>
(A couple of “Key” questions below.)
<separate-key>false [true|false]</separate-key>
(On my GC playout I will have separate Key/fill to my ATEM. “Decklink HD Extreme 3”)
<keyer>external [external|external_separate_device|internal|default]</keyer>
(I think this is just showing the options, and I should type the appropriate one in the code and delete the others?)
<key-device>device + 1 [1..]</key-device>
(What does the +1 represent? These are from the “Channel section below.)

<?xml version="1.0" encoding="utf-8"?>
<!-- CONFIGURATION SECTION -->
<configuration>
   <paths>
      <media-path>media\</media-path>
      <log-path>log\</log-path>
      <data-path>data\</data-path>
      <template-path>templates\</template-path>
      <thumbnails-path>thumbnails\</thumbnails-path>
   </paths>
   <channels>
	<channel>
         <!-- PLAYOUT MONITOR via Screen --> (Right now I am reviewing on the server. Once everything is working and I know what I am doing, I will use a separate laptop to control the client.)
         <video-mode>1080p5994</video-mode>
         <consumers>
            <screen>
               <device>1</device>
            </screen>
	<system-audio />
         </consumers>
      </channel>
      <channel>
         <!-- VIDEO PLAYOUT CHANNEL via Decklink MiniMonitor 4K -->
         <video-mode>1080p5994</video-mode>
         <consumers>
            <decklink>
               <device>2</device>
               <keyer>internal</keyer>
               <embedded-audio>true</embedded-audio>
               <latency>normal</latency>
            </decklink>
         </consumers>
      </channel>
      <channel>
         <!-- CG PLAYOUT CHANNEL via Decklink HD Extreme 3 -->      
         <video-mode>1080p5994</video-mode>
         <consumers>
            <decklink>
               <device>3</device>
               <keyer>external</keyer>
               <embedded-audio>true</embedded-audio>
               <latency>normal</latency>
            </decklink>
         </consumers>
      </channel>
   </channels>
   <controllers>
      <tcp>
         <port>5250</port>
         <protocol>AMCP</protocol>
      </tcp>
   </controllers>
</configuration>
<!—END CONFIGURATION SECTION -->

<!--
<log-level>       trace [trace|debug|info|warning|error]</log-level>
<channel-grid>    false [true|false]</channel-grid>
<mixer>
    <blend-modes>          false [true|false]</blend-modes>
    <straight-alpha>       false [true|false]</straight-alpha>
    <chroma-key>           false [true|false]</chroma-key>
    <mipmapping_default_on>false [true|false]</mipmapping_default_on>
</mixer>
<auto-deinterlace>true  [true|false]</auto-deinterlace>
<auto-transcode>  true  [true|false]</auto-transcode>
<pipeline-tokens> 2     [1..]       </pipeline-tokens>
<template-hosts>
    <template-host>
        <video-mode/>
        <filename/>
        <width/>
        <height/>
    </template-host>
</template-hosts>
<flash>
    <buffer-depth>auto [auto|1..]</buffer-depth>
</flash>
<thumbnails>
    <generate-thumbnails>true [true|false]</generate-thumbnails>
    <width>256</width>
    <height>144</height>
    <video-grid>2</video-grid>
    <scan-interval-millis>5000</scan-interval-millis>
    <generate-delay-millis>2000</generate-delay-millis>
    <video-mode>1080i2997</video-mode>
    <mipmap>false</mipmap>
</thumbnails>
		<!-- CHANNEL SECTION -->
<channels>
    <channel>
<video-mode> NTSC [NTSC|PAL|576p2500|720p2398|720p2500|720p2400|720p5000|720p2997|720p5994|720p3000|720p6000|1080p2398|1080p2400|1080i5000|1080i5994|1080i6000|1080p2500|1080p2997|1080p3000|1080p5000|1080p5994|1080p6000|1556p2398|1556p2400|1556p2500|dci1080p2398|dci1080p2400|dci1080p2500|2160p2398|2160p2400|2160p2500|2160p2997|2160p3000|dci2160p2398|dci2160p2400|dci2160p2500] </video-mode>
<channel-layout>stereo [mono|stereo|dts|dolbye|dolbydigital|smpte|passthru]
</channel-layout>
        <straight-alpha-output>false [true|false]</straight-alpha-output>
        <consumers>
            <decklink>
                <device>[1..]</device>
                <key-device>device + 1 [1..]</key-device>
                <embedded-audio>True [true|false]</embedded-audio>
<channel-layout>stereo [mono|stereo|dts|dolbye|dolbydigital|smpte|passthru]
</channel-layout>
                <latency>normal [normal|low|default]</latency>
                <keyer>external [external|external_separate_device|internal|default]</keyer>
                <key-only>false [true|false]</key-only>
                <buffer-depth>3 [1..]</buffer-depth>
                <custom-allocator>true [true|false]</custom-allocator>
            </decklink>
            <bluefish>
                <device>[1..]</device>
                <embedded-audio>false [true|false]</embedded-audio>
                <channel-layout>stereo [mono|stereo|dts|dolbye|dolbydigital|smpte|passthru]</channel-layout>
                <key-only>false [true|false]</key-only>
            </bluefish>
            
            <screen>
                <device>[0..]</device>
                <aspect-ratio>default [default|4:3|16:9]</aspect-ratio>
                <stretch>fill [none|fill|uniform|uniform_to_fill]</stretch>
                <windowed>false [true|false]</windowed>
                <key-only>false [true|false]</key-only>
                <auto-deinterlace>true [true|false]</auto-deinterlace>
                <vsync>false [true|false]</vsync>
                <name>[Screen Consumer]</name>
                <borderless>false [true|false]</borderless>
            </screen>
            <newtek-ivga>
              <channel-layout>stereo [mono|stereo|dts|dolbye|dolbydigital|smpte|passthru]</channel-layout>
              <provide-sync>true [true|false]</provide-sync>
            </newtek-ivga>
            <file>
                <path></path>
                <vcodec>libx264 [libx264|qtrle]</vcodec>
                <separate-key>false [true|false]</separate-key>
            </file>
            <stream>
                <path></path>
                <args></args>
            </stream>
        </consumers>
    </channel>
</channels>
		<!—END CHANNEL SECTION -->

I assume you are not familiarized with XML file syntax.
The first “part” of the file is the actual configuration, the second part (after the <!— ) is only an example XML with all the options listed into [ ] and, as you said, the default value is the one outside that. Everything contained between <!— and —> is just ignored so you must copy the entries that you need to the top and pick the value you need.
The +1 that you mentioned is just an indication that the device index to use should be the subsequent to the fill device. So if you have a fill device 1, the key should be 2. (There is some cases where this is not correct, mainly with multi-output cards)

So, for the purpose of having a tidy config file is it acceptable to delete all of the text that is after <!— ?
Also if there is a command listed below that you want in your configuration, I would guess you add it to the upper config section?

Example:

<template-hosts>
    <template-host>
        <video-mode/>
        <filename/>
        <width/>
        <height/>
    </template-host>
</template-hosts>

One other question? A bit off topic. I am running Server 2.0.7 & Client 2.0.8 I would like to be able to create some templates in Photoshop, but that is appearantly only supported in 2.1 and newer. Any thought on moving to server 2.1?

I wouldn’t recommend that. Either keep it that way for reference or make a copy of the config file.

Exactly.

About 2.1, depending on the codecs, it’s a bit unpredictable on the performance side. It’s very feature rich but some lags and audio clicks make it somewhat unreliable.

Thank you. I think I will stay with my current setup until I get some more experience under my belt.
After reading what you said about “+1”

The +1 that you mentioned is just an indication that the device index to use should be subsequent to the fill device. So if you have a fill device 1, the key should be 2. (There are some cases where this is not correct, mainly with multi-output cards)

to have separate “Key” & “Fill” I am wondering if I should add a fourth channel?

I am attaching a copy of my current config file.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <paths>
    <media-path>E:\\Media\\</media-path>
    <log-path>log\</log-path>
    <data-path>data\</data-path>
    <template-path>E:\\templates\\</template-path>
    <thumbnails-path>thumbnails\</thumbnails-path>
    <font-path>C:\windows\Fonts/</font-path>
  </paths>
  <lock-clear-phrase>secret</lock-clear-phrase>
<channels>
                         <!--PLAYOUT MONITOR via Screen -->
<channel>		
 <video-mode>1080p5994</video-mode>
  <consumers>
  <screen>
  <device>1</device>
  </screen>
   <system-audio />            
 </consumers>
</channel>	
                        <!--VIDEO PLAYOUT CHANNEL via Decklink MiniMonitor -->
<channel>
<video-mode>1080p5994</video-mode>
  <straight-alpha-output>false</straight-alpha-output>
 <consumers>
    <decklink>
    <device>2</device>
	<keyer>external</keyer>
	<embedded-audio>true</embedded-audio>
	<latency>normal</latency>
	<channel-layout>stereo</channel-layout>
	<key-only>false</key-only>
	<buffer-depth>3</buffer-depth>
	<custom-allocator>true</custom-allocator>
    </decklink>            
</consumers>
</channel>	
                        <!--CG PLAYOUT CHANNEL via Decklink HD Extreme 3 -->
<channel>
<video-mode>1080p5994</video-mode>
  <straight-alpha-output>false</straight-alpha-output>
  <consumers>
     <decklink>
     <device>3</device>
     <keyer>external</keyer>
     <embedded-audio>true</embedded-audio>
     <latency>normal</latency>
     <channel-layout>stereo</channel-layout>
     <key-only>false</key-only>
     <buffer-depth>3</buffer-depth>
     <custom-allocator>true</custom-allocator>
  </decklink>            
 </consumers>
 </channel>
</channels>
<controllers>
<tcp>
   <port>5250</port>
   <protocol>AMCP</protocol>
</tcp>
<tcp>
   <port>5250</port>
   <protocol>LOG</protocol>
</tcp>
  </controllers>
</configuration>

I am using server 2.1 for recording, playing , streaming, graphics and everything for more than two years. I am not using it for playing psd files from Photoshop but the png files from Photoshop for image scroll.

Are you using one of your own clients? Which client version would you recommend I try to test. As I said earlier I think I will stay with my current setup for our upcoming shows, but I would like to test 2.1 to see if it presents any issues for us.

I think there is a basic misunderstanding here. There are no two sections. Casparcg.config is an XML file. In XML You can write comments. So everything between <!-- and --> is ignored by the XML processor. So the “first” configuration section is the only one, that does anything. The “second” section is only to help tom modify the first by telling what settings are valid and what is the default, when that node (in XML terminiology something that starts with a name between < and > and ends with either the same name between </ and >) is omitted.

EDIT: I now scrolled your config file down to the end and there appers a second channel section that is completely false and should not be there. I would suggest you start over from a vanilla config file found in the download.

In the unmodified file. that comes with the download, the line read so, that PAL is the default. But that is not so important. The most important to know is, that this is a list, that shows you what resolutions you can set in the <video-mode> node of a <channel> in the “first” configuration section.

The line should either read:
<embedded-audio>true</embedded-audio> or <embedded-audio>false</embedded-audio>
And it switches the audio embedding in the SDI output on or off. Be aware, that it also adds one frame of latency to the output.
<separate-key> is used to use another output as a key out, when the hardware does not support the output of a key anyway. If you use a Duo 2, Quad 2 or Extreme card you don’t need that.

I don’t really know what <custom-allocator> does I always set it to true.
<lock-clear-phrase> is used with the LOCK commands to allow two clients to control the same server and prevent them from messing with the other ones channel. That setting can normally be ignored.

<separate-key> see above.
<keyer> You answer your own question here. The Extreme should support external for outputing fill and key separtely by the hardware.
<key-device> That is the device number of the card to use if the keyer is set to external_separate_device. It is usually the other devices number +1.

Can you explain? I have two physically different cards. A Decklink MiniMonitor 4K and a Decklink HD Extreme 3. My config file reference both of them. Is this not correct? I playout video on the miniMonitor and playout CG graphic on the HD Extreme.
Device 1 is my screen consumer
Device 2 is my MiniMonitor
Device 3 is my HD Extreme (fill)
I think I should also add a Device 4 for the Key channel from the HD Extreme

I was refering the top most config file in this topic were also the questions were. That file has a configuration block, a commented out part with different stuff and a part entitled channel block, that is NOT commented out. THIS part is wrong and should not be there.

As mentioned the Extreme card has a hardware keyer, that ist activated by setting the mode to external. This outputs the fill and key on two separate BNC‘s WHITOUT any further setting. You can not set a device for that so a device number 4 is invalid in your setup.

After two full days of head-scratching and a lot of back and forth with the great folks on this forum, I have finally got my server working!!! Well, about 98%.

First I removed everything I could to help troubleshoot the problem. For starters, I physically removed my (BMD Decklink MiniMonitor 4K) card and removed the reference to this card and the screen consumer from the config file. I had two cards installed, so I configured the other installed card (BMD HD Extreme 3) and I had success. This was the first time I have been able to play anything out of this card. I then tried to add the screen consumer back into my config, but when I did, I no longer got a signal from my Extreme card. So out with the consumer for now. I removed it from the config file. Now it was time to test to see if I was getting the correct Key & Fill. I opened the “FRAME” Template which a two-box layout.


I could see the colored inmate while connected to HD-SDI Out A. I then moved the connection to HD-SDI Out B where I could see the black & white key image. Perfect!!:grinning:

Next, I reinstalled my MiniMonitor card and added it back into the config file as device “2”. I added some new videos to my rundown. I set the channel to “2” and plugged my monitor into the SDI output and with a very big smile on my face, I watched the video play!!! (Looks like I missed the video resolution. I should have set it to 720p5994)

Back to Channel “1” to make sure things were still working there. All is good.

So earlier I mentioned 98% success! I don’t have the screen consumer configured. I can live without it for now. At some point, I will need to get it working, for when I am working off the server without it being connected to a video monitor or my switcher.

Tomorrow’s task is to reinstall the server in its rack and connect it to my Blackmagic Switcher.

I want to thank everyone that shared their knowledge, experience and most of all showed such patience.
Thank You for your help!!!:grinning::grinning::grinning:

Completed Configuration File.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <paths>
    <media-path>E:\\media\\</media-path>
    <log-path>log\</log-path>
    <data-path>data\</data-path>
    <template-path>E:\\templates\\</template-path>
    <thumbnails-path>thumbnails\</thumbnails-path>
  </paths>

  <channels>
     <channel>
          <video-mode>720p5994</video-mode>
	  <straight-alpha-output>false</straight-alpha-output>
	  <consumers>
	  <decklink>
	  <device>1</device>
	  <embedded-audio>true</embedded-audio>
	  <channel-layout>stereo</channel-layout>
	  <latency>normal</latency>
	  <keyer>external</keyer>
	  <key-only>false</key-only>
	  <buffer-depth>3</buffer-depth>
	  <custom-allocator>true</custom-allocator>
        </decklink>            
       </consumers>
      </channel> 
     
      <channel>
          <video-mode>720p5994</video-mode>
	  <straight-alpha-output>false</straight-alpha-output>
	  <consumers>
	  <decklink>
	  <device>2</device>
	  <embedded-audio>true</embedded-audio>
	  <channel-layout>stereo</channel-layout>
	  <latency>normal</latency>
	  <keyer>external</keyer>
	  <key-only>false</key-only>
	  <buffer-depth>3</buffer-depth>
	  <custom-allocator>true</custom-allocator>
        </decklink>            
       </consumers>
      </channel>
     </channels>
  <controllers>
    <tcp>
        <port>5250</port>
        <protocol>AMCP</protocol>
    </tcp>
  </controllers>
</configuration>
1 Like