Configuration System¶

The configuration system’s functionality revolves around Config.

Common Configurations¶

Config provides several configurable options, including but not limited to:

preview_fps: Frame rate of the preview interface
fps: Frame rate of exported videos

Warning

The frame rate preview_fps of the preview interface and the frame rate fps of exported videos are two different values. This is to accommodate users who may want to lower the frame rate during preview to improve rendering efficiency, and increase the frame rate during export to get smoother videos.

By the way, to improve rendering efficiency during preview, another strategy is to enable the “frame skipping” feature in the “Function” menu at the top left corner of the window.

background_color: Background color of the scene

Warning

When setting the background color, you cannot use forms like background_color='#RRGGBB', you should use

background_color=Color('#RRGGBB')
background_color=Color(BLUE)

and similar forms

font: Default font used by the Text class

You can use either a single string 'Consolas' or a list to provide multiple fallback fonts ['Consolas', 'Noto Serif CJK SC']
output_dir: Output path, with two formats:
- When not starting with the : symbol, it represents a path relative to the working directory, e.g., videos
  
  Use case focuses on placing output files uniformly in the videos folder under the working directory when there is a complex file structure
- When starting with the : symbol, it represents a path relative to the code file where Timeline is located, e.g., :/videos
  
  Use case focuses on placing output files in separate locations near each code file when there is a complex file structure

For more configuration options, refer to the documentation of Config

Setting Configuration - Three Methods¶

Now that we understand these configurations, we also need to know how to set them.

Method One - Timeline Configuration¶

The most common approach is to write the configuration together with your inherited Timeline, for example:

class YourTimeline(Timeline):
    CONFIG = Config(
        preview_fps=10,
        fps=120,
        background_color=Color(PURE_GREEN)
    )

    def construct(self):
        ...

This way, you can change the configuration of YourTimeline at runtime, adjusting the frame rate and background color.

Moreover, configuration information written together with the Timeline class also supports inheritance and overriding:

class AwesomeTemplate(Timeline):
    CONFIG = Config(
        preview_fps=10,
        fps=120,
        output_dir='awesome_videos',
    )

    def construct(self):
        ...

class YourTimeline(AwesomeTemplate):
    CONFIG = Config(
        output_dir=':/local_videos'
    )

    def construct(self):
        ...

In this example, the subclass YourTimeline overrides the parent’s output_dir, while the remaining configurations retain the settings from AwesomeTemplate, which is useful when creating templates and overriding template options.

Method Two - Global Configuration¶

When using command-line arguments, using -c config_name value can modify global configuration, and the set global configuration will override other configurations.

For example, janim write your_file.py YourTimeline -c fps 120 can set the rendering frame rate for this execution to 120.

You can also modify multiple configuration items at the same time, for example:

janim write your_file.py YourTimeline -c fps 120 -c output_dir custom_dir

This command will output the animation at 120 fps to the specified folder custom_dir.

Method Three - Local Configuration¶

Local configuration refers to applying specific configuration only to part of a code block, for example, if you only want to set a special font on a certain segment of code:

class YourTimeline(Timeline):
    def construct(self):
        txt1 = Text('Using default font')

        with Config(font='Noto Serif CJK SC'):
            txt2 = Text('Using "Noto Serif CJK SC" font')

        txt3 = Text('Using default font again')

        group = Group(txt1, txt2, txt3).show()
        group.points.arrange(DOWN, aligned_edge=LEFT)

That is, using with Config(key=value): allows the code block it contains to execute under the specified configuration without affecting the configuration of external code blocks.

Hint

In the above example, you can actually use

txt2 = Text('Using "Noto Serif CJK SC" font', font='Noto Serif CJK SC')

to set the font of txt2, without having to use with Config(font='Noto Serif CJK SC'):, this is just an example to demonstrate the usage of local configuration.

Getting Configuration¶

These configurations are generally used to change some behaviors of JAnim during rendering after modification. If you need to manually get the specific value of a configuration item, you can use the form Config.get.xxx, for example:

class YourTimeline(Timeline):
    CONFIG = Config(
        preview_fps=10,
        fps=120,
    )

    def construct(self):
        print(Config.get.preview_fps)
        print(Config.get.fps)
        print(Config.get.frame_width, Config.get.frame_height)

        print(Config.get.left_side, Config.get.right_side)
        print(Config.get.bottom, Config.get.top)

Attributes that are not set will use the default settings default_config

Hint

In this example, we output the values of configuration items preview_fps fps frame_width frame_height.

However, the left_side right_side bottom top involved in the last two lines are not directly configurable options, but are determined by the viewport size configurations frame_width and frame_height. This is equivalent to providing a kind of “derived functionality”.