Scratchpad:Implementation of Parts and Translations

From OpenLP
Jump to: navigation, search

This is a suggestion, how to implement support for parts, translations and -literations. Currently this are my (M²j) own ideas. There is not jet any feedback from a core developer. Feel invited to make your suggestions.

I'm looking forward to hear your suggestions and ideas.

Songs plugin

The two basic options to define languages in floationg text are per line definition and block definition. I think blockwise definition is more smooth to read. But I didn't find any nice method to define grouping in blockwise definition. So here is a suggestion for linewise definition:

This are the rules:

  • Page breaks are permitted, when a line starts with a plus (+).
  • Special line attributes are introduces with special characters and terminated with a colon (:).
  • Parts are introduced by a at sign (@)
  • Translations are introduced by a sharp (#)
  • Transliterations are introduced by a dollar sign ($)

Some simple example:

Nearerm my God, to Thee, nearer to Thee!
+#de: Näher, mein Gott, zu dir, näher zu dir.
E'en though it be a cross that raiseth me.
+#de: Drückt mich auch Kummer hier, drohet man mir,
still al my song shall be, nearermy God to Thee,
+#de: soll doch trotz Kreutz und Pein dies meine Losung sein:
nearer my God to Thee, nerer to Thee.
+#de: Näher, mein Gott, zu dir, näher zu dir!
Though like the wanderer, The sun gone down,
+#de: Bricht mir, wie Jakob, dort Nacht auch herein,

Also one more complicated:

@men: And I will love and adore Him,
+@men#de: Und ich will ihm lieben und anbeten,
+@women: You are Alpha, Omega,
+@women#de: Du bist der Erste und Letzte,
+@women: Beginning and End,
+@women#de: Anfang und Ende,
@men: an I will bow down before Him.
+@men#de: und ich will mich vor ihm verbeugen.
+@women: You’re my Saviour, Messiah,
+@women#de: Du bist mein Retter, Messias,
+@women: Redeemer and Friend.
+@women#de: Erlöser und Freund.
You’re my Prince of Peace,
+#de: Du bist mein Friedensprinz
and I will live my life for You.
+#de: und ich will für dich leben.

I think the syntax @men: is quite intuitive and still offers much flexibility. As we just check the character in the first column all texts (or HTML tags) are possible if you put a space in the first column.

Still there is the question, if the part tags are equal to displayed part labels. If not: How can we define them in the GUI. Part labels would be nice to display them just once each slide instead of every line.

The Songs plugin has to assign parts, translations and -literations to textClasses. If they aren't assigned, they are not displayed.

-This looks good, but I can see OpenLyrics integration could be an issue. Looking at the OpenLyrics documentation, it appears that only verse tags can carry the language attribute. The lines tag can carry male / female parts. This would seem to limit OpenLP to block display of languages if we were to stick to OpenLyrics. --Phill 15:00, 18 February 2013 (SAST)

Well, I discussed about that once. When looking at the specification now, v0.7 does not seem to include linewise language declaration. Maybe this was only by accident, as there should be no reason to distinguish between translations, -literations and parts. I think this can be fixed in OpenLyrics.
There also one other missing feature: OpenLyrics does not define grouping of lines to control the position of a slide break. This is necessary for more complex cases (see example above). Still I think we can start working on this extentions to OpenLyrics at the time until we have some real code in OpenLP. Then we know in more detail about what makes sense.
--M²j 16:37, 16 September 2013 (SAST)


A theme should consist out of a set of areas, textClasses and general properties.

General properties are covering background and slide transition properties.

A area defines:

  • identifier (area's name)
  • location on the screen (X, Y, width, height) [absolute (px)|relative (%)]
  • layer, a index to define the stack order.
  • text_alignment (horizontal, vertical)
  • wrap_indentation

A textClass defines:

  • identifier (textClass's name) \\ I assume, that here any name is allowed. It has to be checked, if a additional international name is necessary
  • font with the properties: name, proportion, weight, italics and color
  • outline with the properties: width and color
  • shadow with the properties: x-offset, y-offset and color
  • line_adjustment
  • area, the area in which the text is displayed

The required textClasses are main and footer. Other classes can be added on a dynamic base. Undefined parameters will be derived from main.

The song plugin defines a textClass for each string. According to the area of this textClass it is layouted on the screen.

If more than one textClass is assigned to a area, the text gets stacked in the order the lines are received from the songs plugin. Later this might get enhanced by enabling translations in blocks on a area level for example.

If the song plugin links to a invalid textClass, the text is displayed by the main class.

This changes the theme XML format. My first draft would just enhance it, but I think as long we are alpha software, this is the better way.

Other ideas

  • A textClass may have the attribute persistent. This defines, that the label is repeated on each slide. This way we can allow for example to display a song title or a sermon subject on each slide. This would also allow to decide whether to show the copyright informations just on the first slide or permanent (I don’t know, how the policies of CCLI are, but AFAIK VG Musikedition permits this).
  • A media object may define a image, video, solid color or gradient, which may be assigned to a area. So you can display a church logo, etc. without integrating it in the background image. This way you can also threat the background (maybe with the obligatory area screen).
  • A media object should have the property fitting. This property can be none to show the item native resolution, stretch to stretch the item to the area size, proportional to scale proportional on the area or crop to stretch it proportional and crop away borders that it's filling the area.

Proposed new Theme Schema

Some names are renamed slidely (the above names were partially choosen to improve readability by taking names which are not colliding with natural words). I wrote it in camelCase, while the current scheme combines camelCase and lower_case_with_underscores. The use of the parameter persistent is not shown yet.

<?xml version="1.0" encoding="utf-8"?>
<theme version="2.0">
  <!-- The "main" area is the primary content area. -->
  <area name="main">
    <!-- Optional for "main" and "footer" area: overwrites the automatic location.
         The scale can be either "relative" or in screen "pixels".-->
    <location x="0.04" y="0.06" width="0.92" height="0.54" scale="relative"/>
    <!-- The stack order of the layer. -->
    <layer number="1"/>
    <!-- Optional: Alignment for text content 
         vertical="top"|"middle"|"bottom" -->
    <textAlignment horizontal="left" vertical="top"/>
  <area name="footer">
    <location x="0.7" y="0.62" width="0.26" height="0.42" scale="relative"/>
    <layer number="1"/>
    <textAlignment horizontal="right" vertical="bottom"/>
  <!-- Optional: Additional content areas -->
  <area name="Übersetzung">
    <location x="0.04" y="0.62" width="0.66" height="0.42" scale="relative"/>
    <layer number="1"/>
  <!-- Properties of a text class. "main" and "footer" are manditory -->
  <text name="main">
    <!-- Font characteristics -->
    <font name="Dejavu Sans" size="28" weight="bold" italics="False" color="#FFFFFF"/>
    <!-- Optional: Font outline -->
    <outline show="True" width="1" color="#000000"/>
    <!-- Optional: Font shaddow -->
    <shadow show="True" x-offset="2", y-offset="2" color="000000"/>
    <!-- Optional: Line spacing adjustment -->
    <lineSpacing adjustment="0"/>
    <!-- Area this text object is displayed in -->
    <area name="main">
  <text name="footer">
    <font name="Dejavu Sans" size="12" color="#FFFFFF"/>
    <area name="footer">
  <!-- Optional: Additional text classes -->
  <text name="translation 1">
    <!-- All parameters which are not given are derived from the "main" text class -->
    <font size="24" color="#D0D0FF"/>
    <area name="main">
  <text name="translation 2">
    <font size="24"/>
    <area name="Übersetzung">
  <!-- Optional: Media classes can be given to fill areas with non-text content. -->
  <media name="Some Frame">
    <!-- One tag can be either "image", "video", "plain" or "gradient"
         images and videos have the parameter fitting="none"|"stretch"|"proportional"|"crop" -->
    <plain color="#FFFFFF20"/>
    <!-- Area the media class is assigned to. -->
    <area name="Übersetzung">
  <!-- The background tag can have any of a media class content, but it refers to the whole screen area. -->
    <image filename="fred.bmp" backgroundColor="#000000" fitting="stretch"/>


I have a small sample implementation of the rendering in Qt/C++ using QPainter:

Parts and Translations POC Screen.png