Please report issues or browse a list of known issues at See Known issues for instructions on how to report issues related to an unknown codec.

Known issues

  • storyboard uses PIL.ImageFont from Pillow to draw text, which is rather primitive and only allows one font at a time (no fallback). The default font packaged is Source Code Pro Regular, which only draws its supported code points, and leave unknown code points as boxes. In particular, there is no CJK support, so CJK characters in video filenames won’t come out very nice.

    You can specify your own font file that covers (part of) CJK code points, but the catch is that you should really use fixed-width fonts (unless you want to blow up the beautiful formatting, in which case you might as well use a proprietary player to generate a storyboard that’s bad-looking inside out). It’s basically impossible to have a truly fixed-width font that mixes CJK glyphs with Latin glyths, since they are so different — CJK glyphs are intrinsically square-shaped, while Latin glyphs are not. This is just a sad fact of life and there’s nothing we can do about it. Therefore, there’s no CJK support in storyboard (CJK characters won’t break storyboard — they just come out as boxes). Hopefully you’re using ASCII filenames anyway; if you’re not, you really should.

  • treats each codec separately, and the list of supported codecs is far from complete (currently the list is mostly what I encounter in day-to-day use). If you encounter an audio/video/subtitle codec that triggers stupid output, please report an issue or open a pull request. If it’s not a commonly seen codec and cannot be encoded by FFmpeg, please try to link a sample video with the relevant codec so that I can inspect and test.

  • ffprobe might report the wrong duration for certain VOB or other videos, which screws up the whole thing. See issue #3. As a fallback, you can use the option --video-duration of storyboard (see CLI reference), or if you are using the API, the optional parameter video_duration to storyboard.storyboard.StoryBoard or storyboard.metadata.Video (see API reference). Note, however, that the implementation of frame extraction in this case requires decoding frame by frame, an aspect that is unlikely to be improved; worse still, the current implementation requires decoding from the beginning of the video for each storyboard frame, so the whole process takes extremely long. This problem is documented in issue #24 and might be improved in the future.