From 28224b347dd993d635ba8a0f2e7db20130483bd4 Mon Sep 17 00:00:00 2001 From: Carl Hetherington Date: Thu, 27 Jul 2017 13:12:12 +0100 Subject: [PATCH] Add some documentation for config.xml. --- doc/manual/Makefile | 9 ++-- doc/manual/dcpomatic.xml | 18 ++++++++ src/lib/config.cc | 91 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 115 insertions(+), 3 deletions(-) diff --git a/doc/manual/Makefile b/doc/manual/Makefile index 324c31cf3..9e74b4dff 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -65,11 +65,14 @@ diagrams/%.png: diagrams/%.svg diagrams/%.pdf: diagrams/%.svg inkscape -z -f $< --export-pdf $@ --export-area-drawing +config.xml: ../../src/lib/config.cc config.py + python config.py ../../src/lib/config.cc > config.xml + # # HTML # -html: $(XML) dcpomatic-html.xsl extensions-html.ent dcpomatic.css \ +html: $(XML) config.xml dcpomatic-html.xsl extensions-html.ent dcpomatic.css \ $(addprefix html/screenshots/,$(SCREENSHOTS)) \ $(subst .svg,.png,$(addprefix diagrams/,$(DIAGRAMS))) \ @@ -89,7 +92,7 @@ html: $(XML) dcpomatic-html.xsl extensions-html.ent dcpomatic.css \ # PDF # -pdf: $(XML) dcpomatic-pdf.xsl extensions-pdf.ent \ +pdf: $(XML) config.xml dcpomatic-pdf.xsl extensions-pdf.ent \ $(addprefix screenshots/,$(SCREENSHOTS)) \ $(subst .svg,.pdf,$(addprefix diagrams/,$(DIAGRAMS))) @@ -106,7 +109,7 @@ pdf: $(XML) dcpomatic-pdf.xsl extensions-pdf.ent \ # LaTeX (handy for debugging) # -tex: $(XML) dcpomatic-pdf.xsl extensions-pdf.ent +tex: $(XML) config.xml dcpomatic-pdf.xsl extensions-pdf.ent # The DocBook needs to know what file extensions to look for # for screenshots and diagrams; use the correct file to tell it. diff --git a/doc/manual/dcpomatic.xml b/doc/manual/dcpomatic.xml index bed0242f3..bd42747de 100644 --- a/doc/manual/dcpomatic.xml +++ b/doc/manual/dcpomatic.xml @@ -3317,4 +3317,22 @@ The full details of OV and VF files are discussed in + + +Configuration files + +Most of DCP-o-matic's configuration is stored in an XML file called config.xml. This is stored in different places depending on your operating system: + + + Windows: c:\Users\your_user_name\AppData\Local\dcpomatic + OS X: /Users/your_user_Name/Library/Preferences/com.dcpomatic/2 + Linux: ~/.config/dcpomatic2 + + +Possible XML tags are as follows: + + + + + diff --git a/src/lib/config.cc b/src/lib/config.cc index 02724e695..6c44e5153 100644 --- a/src/lib/config.cc +++ b/src/lib/config.cc @@ -424,77 +424,148 @@ Config::write_config () const xmlpp::Document doc; xmlpp::Element* root = doc.create_root_node ("Config"); + /* [XML] Version The version number of the configuration file format; currently 2. */ root->add_child("Version")->add_child_text ("2"); + /* [XML] MasterEncodingThreads Number of encoding threads to use when running as master. */ root->add_child("MasterEncodingThreads")->add_child_text (raw_convert (_master_encoding_threads)); + /* [XML] ServerEncodingThreads Number of encoding threads to use when running as server. */ root->add_child("ServerEncodingThreads")->add_child_text (raw_convert (_server_encoding_threads)); if (_default_directory) { + /* [XML:opt] DefaultDirectory Default directory when creating a new film in the GUI. */ root->add_child("DefaultDirectory")->add_child_text (_default_directory->string ()); } + /* [XML] ServerPortBase Port number to use for frame encoding requests. ServerPortBase + 1 and + ServerPortBase + 2 are used for querying servers. ServerPortBase + 3 is used + by the batch converter to listen for job requests. + */ root->add_child("ServerPortBase")->add_child_text (raw_convert (_server_port_base)); + /* [XML] UseAnyServers 1 to broadcast to look for encoding servers to use, 0 to use only those configured. */ root->add_child("UseAnyServers")->add_child_text (_use_any_servers ? "1" : "0"); BOOST_FOREACH (string i, _servers) { + /* [XML:opt] Server IP address or hostname of an encoding server to use; you can use as many of these tags + as you like. + */ root->add_child("Server")->add_child_text (i); } + /* [XML] OnlyServersEncode 1 to set the master to do decoding of source content no JPEG2000 encoding; all encoding + is done by the encoding servers. 0 to set the master to do some encoding as well as coordinating the job. + */ root->add_child("OnlyServersEncode")->add_child_text (_only_servers_encode ? "1" : "0"); + /* [XML] TMSProtocol Protocol to use to copy files to a TMS; 0 to use SCP, 1 for FTP. */ root->add_child("TMSProtocol")->add_child_text (raw_convert (static_cast (_tms_protocol))); + /* [XML] TMSIP IP address of TMS */ root->add_child("TMSIP")->add_child_text (_tms_ip); + /* [XML] TMSPath Path on the TMS to copy files to */ root->add_child("TMSPath")->add_child_text (_tms_path); + /* [XML] TMSUser Username to log into the TMS with */ root->add_child("TMSUser")->add_child_text (_tms_user); + /* [XML] TMSPassword Password to log into the TMS with */ root->add_child("TMSPassword")->add_child_text (_tms_password); if (_cinema_sound_processor) { + /* [XML:opt] CinemaSoundProcessor Identifier of the type of cinema sound processor to use when calculating + gain changes from fader positions. Currently can only be dolby_cp750. + */ root->add_child("CinemaSoundProcessor")->add_child_text (_cinema_sound_processor->id ()); } if (_language) { + /* [XML:opt] Language Language to use in the GUI e.g. fr_FR. */ root->add_child("Language")->add_child_text (_language.get()); } if (_default_container) { + /* [XML:opt] DefaultContainer ID of default container to use when creating new films (119, 133, + 138, 143, 166, 178, 185, 235, + 239 or full-frame). + */ root->add_child("DefaultContainer")->add_child_text (_default_container->id ()); } if (_default_scale_to) { + /* [XML:opt] DefaultScaleTo ID of default ratio to scale content to when creating new films + (see DefaultContainer for IDs). + */ root->add_child("DefaultScaleTo")->add_child_text (_default_scale_to->id ()); } if (_default_dcp_content_type) { + /* [XML:opt] DefaultDCPContentType Default content type ot use when creating new films (FTR, SHR, + TLR, TST, XSN, RTG, TSR, POL, + PSA or ADV). */ root->add_child("DefaultDCPContentType")->add_child_text (_default_dcp_content_type->isdcf_name ()); } + /* [XML] DefaultDCPAudioChannels Default number of audio channels to use when creating new films. */ root->add_child("DefaultDCPAudioChannels")->add_child_text (raw_convert (_default_dcp_audio_channels)); + /* [XML] DCPIssuer Issuer text to write into CPL files. */ root->add_child("DCPIssuer")->add_child_text (_dcp_issuer); + /* [XML] DCPIssuer Creator text to write into CPL files. */ root->add_child("DCPCreator")->add_child_text (_dcp_creator); + /* [XML] ISDCFMetadata Default ISDCF metadata to use for new films; child tags are <ContentVersion>, + <AudioLanguage>, <SubtitleLanguage>, <Territory>, + <Rating>, <Studio>, <Facility>, <TempVersion>, + <PreRelease>, <RedBand>, <Chain>, <TwoDVersionOFThreeD>, + <MasteredLuminance>. + */ _default_isdcf_metadata.as_xml (root->add_child ("ISDCFMetadata")); + /* [XML] DefaultStillLength Default length (in seconds) for still images in new films. */ root->add_child("DefaultStillLength")->add_child_text (raw_convert (_default_still_length)); + /* [XML] DefaultJ2KBandwidth Default bitrate (in bits per second) for JPEG2000 data in new films. */ root->add_child("DefaultJ2KBandwidth")->add_child_text (raw_convert (_default_j2k_bandwidth)); + /* [XML] DefaultAudioDelay Default delay to apply to audio (positive moves audio later) in milliseconds. */ root->add_child("DefaultAudioDelay")->add_child_text (raw_convert (_default_audio_delay)); + /* [XML] DefaultInterop 1 to default new films to Interop, 0 for SMPTE. */ root->add_child("DefaultInterop")->add_child_text (_default_interop ? "1" : "0"); if (_default_kdm_directory) { + /* [XML:opt] DefaultKDMDirectory Default directory to write KDMs to. */ root->add_child("DefaultKDMDirectory")->add_child_text (_default_kdm_directory->string ()); } + /* [XML] MailServer Hostname of SMTP server to use. */ root->add_child("MailServer")->add_child_text (_mail_server); + /* [XML] MailPort Port number to use on SMTP server. */ root->add_child("MailPort")->add_child_text (raw_convert (_mail_port)); + /* [XML] MailUser Username to use on SMTP server. */ root->add_child("MailUser")->add_child_text (_mail_user); + /* [XML] MailPassword Password to use on SMTP server. */ root->add_child("MailPassword")->add_child_text (_mail_password); + /* [XML] KDMSubject Subject to use for KDM emails. */ root->add_child("KDMSubject")->add_child_text (_kdm_subject); + /* [XML] KDMFrom From address to use for KDM emails. */ root->add_child("KDMFrom")->add_child_text (_kdm_from); BOOST_FOREACH (string i, _kdm_cc) { + /* [XML] KDMCC CC address to use for KDM emails; you can use as many of these tags as you like. */ root->add_child("KDMCC")->add_child_text (i); } + /* [XML] KDMBCC BCC address to use for KDM emails */ root->add_child("KDMBCC")->add_child_text (_kdm_bcc); + /* [XML] KDMEmail Text of KDM email */ root->add_child("KDMEmail")->add_child_text (_kdm_email); + /* [XML] CheckForUpdates 1 to check dcpomatic.com for new versions, 0 to check only on request */ root->add_child("CheckForUpdates")->add_child_text (_check_for_updates ? "1" : "0"); + /* [XML] CheckForUpdates 1 to check dcpomatic.com for new text versions, 0 to check only on request */ root->add_child("CheckForTestUpdates")->add_child_text (_check_for_test_updates ? "1" : "0"); + /* [XML] MaximumJ2KBandwidth Maximum J2K bandwidth (in bits per second) that can be specified in the GUI */ root->add_child("MaximumJ2KBandwidth")->add_child_text (raw_convert (_maximum_j2k_bandwidth)); + /* [XML] AllowAnyDCPFrameRate 1 to allow users to specify any frame rate when creating DCPs, 0 to limit the GUI to standard rates */ root->add_child("AllowAnyDCPFrameRate")->add_child_text (_allow_any_dcp_frame_rate ? "1" : "0"); + /* [XML] LogTypes Types of logging to write; a bitfield where 1 is general notes, 2 warnings, 4 errors, 8 debug information related + to encoding, 16 debug information related to encoding, 32 debug information for timing purposes, 64 debug information related + to sending email. + */ root->add_child("LogTypes")->add_child_text (raw_convert (_log_types)); + /* [XML] AnalyseEBUR128 1 to do EBUR128 analyses when analysing audio, otherwise 0. */ root->add_child("AnalyseEBUR128")->add_child_text (_analyse_ebur128 ? "1" : "0"); + /* [XML] AutomaticAudioAnalysis 1 to run audio analysis automatically when audio content is added to the film, otherwise 0. */ root->add_child("AutomaticAudioAnalysis")->add_child_text (_automatic_audio_analysis ? "1" : "0"); #ifdef DCPOMATIC_WINDOWS + /* [XML] Win32Console 1 to open a console when running on Windows, otherwise 0. */ root->add_child("Win32Console")->add_child_text (_win32_console ? "1" : "0"); #endif + /* [XML] Signer Certificate chain and private key to use when signing DCPs and KDMs. Should contain <Certificate> + tags in order and a <PrivateKey> tag all containing PEM-encoded certificates or private keys as appropriate. + */ xmlpp::Element* signer = root->add_child ("Signer"); DCPOMATIC_ASSERT (_signer_chain); BOOST_FOREACH (dcp::Certificate const & i, _signer_chain->unordered()) { @@ -502,6 +573,7 @@ Config::write_config () const } signer->add_child("PrivateKey")->add_child_text (_signer_chain->key().get ()); + /* [XML] Decryption Certificate chain and private key to use when decrypting KDMs */ xmlpp::Element* decryption = root->add_child ("Decryption"); DCPOMATIC_ASSERT (_decryption_chain); BOOST_FOREACH (dcp::Certificate const & i, _decryption_chain->unordered()) { @@ -509,29 +581,48 @@ Config::write_config () const } decryption->add_child("PrivateKey")->add_child_text (_decryption_chain->key().get ()); + /* [XML] History Filename of DCP to present in the File menu of the GUI; there can be more than one + of these tags. + */ BOOST_FOREACH (boost::filesystem::path i, _history) { root->add_child("History")->add_child_text (i.string ()); } + /* [XML] DKDMGroup A group of DKDMs, each with a Name attribute, containing other <DKDMGroup> + or <DKDM> tags. + */ + /* [XML] DKDM A DKDM as XML */ _dkdms->as_xml (root); + /* [XML] CinemasFile Filename of cinemas list file */ root->add_child("CinemasFile")->add_child_text (_cinemas_file.string()); + /* [XML] ShowHintsBeforeMakeDCP 1 to show hints in the GUI before making a DCP, otherwise 0 */ root->add_child("ShowHintsBeforeMakeDCP")->add_child_text (_show_hints_before_make_dcp ? "1" : "0"); + /* [XML] ConfirmKDMEmail 1 to confirm before sending KDM emails in the GUI, otherwise 0 */ root->add_child("ConfirmKDMEmail")->add_child_text (_confirm_kdm_email ? "1" : "0"); + /* [XML] KDMFilenameFormat Format for KDM filenames */ root->add_child("KDMFilenameFormat")->add_child_text (_kdm_filename_format.specification ()); + /* [XML] KDMContainerNameFormat Format for KDM containers (directories or ZIP files) */ root->add_child("KDMContainerNameFormat")->add_child_text (_kdm_container_name_format.specification ()); + /* [XML] DCPMetadataFilenameFormat Format for DCP metadata filenames */ root->add_child("DCPMetadataFilenameFormat")->add_child_text (_dcp_metadata_filename_format.specification ()); + /* [XML] DCPAssetFilenameFormat Format for DCP asset filenames */ root->add_child("DCPAssetFilenameFormat")->add_child_text (_dcp_asset_filename_format.specification ()); + /* [XML] JumpToSelected 1 to make the GUI jump to the start of content when it is selected, otherwise 0 */ root->add_child("JumpToSelected")->add_child_text (_jump_to_selected ? "1" : "0"); + /* [XML] Nagged 1 if a particular nag screen has been shown and should not be shown again, otherwise 0 */ for (int i = 0; i < NAG_COUNT; ++i) { xmlpp::Element* e = root->add_child ("Nagged"); e->set_attribute ("Id", raw_convert(i)); e->add_child_text (_nagged[i] ? "1" : "0"); } + /* [XML] PreviewSound 1 to use sound in the GUI preview, otherwise 0 */ root->add_child("PreviewSound")->add_child_text (_preview_sound ? "1" : "0"); if (_preview_sound_output) { + /* [XML:opt] PreviewSoundOutput Name of the audio output to use */ root->add_child("PreviewSoundOutput")->add_child_text (_preview_sound_output.get()); } + /* [XML] CoverSheet Text of the cover sheet to write when making DCPs */ root->add_child("CoverSheet")->add_child_text (_cover_sheet); try { -- 2.30.2