Comparison between KBP converters
=================================

.. note:: This is currently a draft so some information may not yet be correct. I'll remove this notice when it's been verified.

There are several projects that can import .kbp files in some capacity. Here's a summary of the functionality differences. If I'm missing anything or you have any corrections, please feel free to reach out `via email <mailto:code@itmightbekaraoke.com?subject=kbp2video%20doc%20updates>`_.

Karaoke Mugen is not listed here because it uses kbp2ass. However, note that it specifies options that retime display/remove and disable the positional functionality.

For Kadda OK Tools, the functionality below represents importing KBP and exporting for YouTube Movie Maker (YTMM).

.. list-table::
   :header-rows: 1

   * - Feature
     - kbp2video/kbputils
     - `kbp2ass <https://github.com/Aeden-B/kbp2ass>`_ [#f1]_
     - `Kadda OK Tools <https://github.com/KaddaOK/KaddaOKTools>`_
     - `Karaoke Lyrics Editor <https://www.ulduzsoft.com/linux/karaoke-lyrics-editor/>`_
   * - Syllable wipe timing
     - Yes
     - Yes [#f2]_
     - Yes [#f2]_
     - Limited [#f3]_
   * - Line display/remove
     - Yes
     - Yes
     - Yes [#f4]_
     - No
   * - Track Offset
     - Yes
     - Yes
     - No
     - No
   * - Styles
     - Yes
     - Yes
     - Partial [#f5]_
     - No
   * - Export to KBP
     - No [#f6]_
     - No [#f6]_
     - Yes
     - No
   * - Edit timings within app / from exported file
     - No [#f7]_ / Yes (.ass)
     - No [#f7]_ [#f8]_ / Yes (.ass)
     - Yes / Yes (.kbp or YTMM)
     - Yes / Yes (.lrc)
   * - Line alignment
     - Yes
     - Yes
     - Yes
     - No
   * - Line positions
     - Yes
     - Yes
     - No [#f9]_
     - No
   * - Wipe detail
     - Yes [#f10]_
     - Yes [#f10]_
     - No [#f11]_
     - No [#f11]_
   * - Background color retrieval
     - Yes [#f12]_
     - No
     - Yes
     - No
   * - Audio file retrieval
     - Yes [#f12]_
     - No
     - Yes
     - No
   * - Set fade-in/fade-out
     - Yes
     - Yes
     - Yes [#f13]_
     - No
   * - Change aspect ratio
     - Yes
     - Yes
     - Yes [#f14]_
     - Yes
   * - Swap audio
     - Yes
     - Yes
     - Yes
     - Yes
   * - Add background image/video
     - Yes
     - Yes
     - Yes
     - Partial [#f15]_
   * - Add intro/outro
     - Yes
     - Yes
     - Yes [#f13]_
     - Partial [#f15]_
   * - Add automatic lead-ins
     - No
     - No
     - Yes
     - Limited [#f17]_
   * - Apply a template
     - No
     - No
     - Yes
     - No
   * - Batch processing of multiple files
     - Yes
     - Yes [#f18]_
     - No
     - No

.. rubric:: Notes

.. [#f1] Windows builds can be found in the `ItMightBeKaraoke fork <https://github.com/ItMightBeKaraoke/kbp2ass/releases>`_. See also `this page <https://itmightbekaraoke.com/kbp2ass/>`_ for a bit more information about kbp2ass.
.. [#f2] In some cases the start or end time may be off by 10ms
.. [#f3] Only the start time of syllables are captured, i.e. gaps are not accounted for
.. [#f4] In some cases these may be retimed
.. [#f5] The palette is retained, but some aspects of the styles themselves are not, including their palette mappings
.. [#f6] There is not much point currently for these since they don't modify any of the KBS parameters. A future release may include some functions like adding lead-ins or shifting timestamps, in which case export would be added so those additions could be retained for KBS's own CDG export as well.
.. [#f7] While there is not a general way to edit timings, there is a function to set an offset for the exported .ass file
.. [#f8] While there is not a general way to edit timings, line display/remove can be retimed to set values before start of wipe, and after end of wipe.
.. [#f9] Pages are limited to 4 lines, but if you have 4 or less lines per page, your page breaks will be retained. However, if you use gap lines or an across/down position, those will not be kept.
.. [#f10] Detail levels 1-4 are treated the same way (progressive) and level 5 is word by word. See :ref:`limitations:Implementation Differences` for rationale.
.. [#f11] Always uses progressive wiping
.. [#f12] Not included in the .ass file created by kbputils, because there is no place for it to go, but it is understood by the library and pulled in when using kbp2video.
.. [#f13] Externally through YTMM after export
.. [#f14] Text area can be sized arbitrarily through YTMM after export
.. [#f15] Images and CDG graphics can be included for CDG export only
.. [#f17] They can only occur at the start of pages
.. [#f18] Not explicitly supported by kbp2ass itself, but it's a command-line utility and library, so it can be scripted, and previous versions of kbp2video did so to enable this functionality.