timeline

class janim.anims.timeline.Timeline(*args, **kwargs)

基类：object

继承该类并实现 construct() 方法，以实现动画的构建逻辑

调用 build() 可以得到构建完成的 Timeline 对象

CONFIG: Config | None = None

在子类中定义该变量可以起到设置配置的作用，例如：

class Example(Timeline):
    CONFIG = Config(
        font=['Consolas', 'LXGW WenKai Lite']
    )

    def construct(self) -> None:
        ...

另见：Config

ctx_var: ContextVar = <ContextVar name='Timeline.ctx_var'>

static get_context(raise_exc=True) → Timeline | None

调用该方法可以得到当前正在构建的 Timeline 对象

• 如果在 construct() 方法外调用，且 raise_exc=True （默认），则抛出 TimelineLookupError

class ScheduledTask(at: float, func: Callable, args: list, kwargs: dict)

基类：object

另见 schedule()

at: float

func: Callable

args: list

kwargs: dict

class TimeOfCode(time: float, line: int)

基类：object

标记 construct() 执行到的代码行数所对应的时间

time: float

line: int

class PausePoint(at: 'float', at_previous_frame: 'bool')

基类：object

at: float

at_previous_frame: bool

class PlayAudioInfo(audio: Audio, range: TimeRange, clip_range: TimeRange)

基类：object

调用 play_audio() 的参数信息

audio: Audio

range: TimeRange

clip_range: TimeRange

class SubtitleInfo(text: str, range: TimeRange, kwargs: dict, subtitle: Text | TypstText)

基类：object

调用 subtitle() 的参数信息

text: str

range: TimeRange

kwargs: dict

subtitle: Text | TypstText

class AdditionalRenderCallsCallback(t_range: 'TimeRange', func: 'RenderCallsFn')

基类：object

t_range: TimeRange

func: RenderCallsFn

abstractmethod construct() → None

继承该方法以实现动画的构建逻辑

build_indent_ctx: ContextVar = <ContextVar name='Timeline.build_indent_ctx'>

build(*, quiet=False, hide_subtitles=False, show_debug_notice=False) → BuiltTimeline

构建动画并返回

with_config()

如果是第一次调用，会在当前 context 的基础上作用定义在 Timeline 子类中的 config，并记录

如果是之后的调用，则会直接设置为已记录的，确保在不同情境下的一致性

schedule(at: float, func: Callable, *args, **kwargs) → None

计划执行

会在进度达到 at 时，对 func 进行调用， 可传入 *args 和 **kwargs

schedule_and_detect_changes(at: float, func: Callable, *args, **kwargs) → None

与 schedule() 类似，但是在调用 func 后会记录变化的物件的状态

timeout(delay: float, func: Callable, *args, **kwargs) → None

相当于 schedule(self.current_time + delay, func, *args, **kwargs)

timeout_and_detect_changes(delay: float, func: Callable, *args, **kwargs) → None

与 timeout() 类似，但是在调用 func 后会记录变化的物件的状态

forward(dt: float = 1, *, _detect_changes=True, _record_lineno=True)

向前推进 dt 秒

forward_to(t: float, *, _detect_changes=True) → None

向前推进到 t 秒的时候

prepare(*anims: SupportsAnim, at: float = 0, name: str | None = 'prepare', **kwargs) → TimeRange

play(*anims: SupportsAnim, name: str | None = 'play', **kwargs) → TimeRange

pause_point(*, offset: float = 0, at_previous_frame: bool = True) → None

标记在预览界面中，执行到当前时间点时会暂停

• at_previous_frame 控制是在前一帧暂停（默认）还是在当前帧暂停

• offset 表示偏移多少秒，例如 offset=2 则是当前位置 2s 后

• 在 GUI 界面中，可以使用 Ctrl+左方向键 快速移动到前一个暂停点，Ctrl+右方向键 快速移动到后一个

aas(file_path: str, subtitle: str | Iterable[str], **kwargs) → TimeRange

audio_and_subtitle() 的简写

audio_and_subtitle(file_path: str, subtitle: str | Iterable[str], *, clip: tuple[float, float] | None | EllipsisType = Ellipsis, delay: float = 0, mul: float | Iterable[float] | None = None, **subtitle_kwargs) → TimeRange

播放音频，并在对应的区间显示字幕

• 如果 clip=... （默认，省略号），则表示自动确定裁剪区间，将前后的空白去除（可以传入 clip=None 禁用自动裁剪）

• 如果 mul 不是 None，则会将音频振幅乘以该值

play_audio(audio: Audio, *, delay: float = 0, begin: float = 0, end: float = -1, clip: tuple[float, float] | None = None) → TimeRange

在当前位置播放音频

• 可以指定 begin 和 end 表示裁剪区段

• 可以指定在当前位置往后 delay 秒才开始播放

• 若指定 clip，则会覆盖 begin 和 end （可以将 clip 视为这二者的简写）

返回值表示播放的时间段

has_audio() → bool

该 Timeline 自身是否有可以播放的音频

has_audio_for_all() → bool

考虑所有子 Timeline，是否有可以播放的音频

subtitle(text: str | Iterable[str], duration: float = 1, delay: float = 0, scale: float | Iterable[float] = 0.8, use_typst_text: bool | Iterable[bool] = False, surrounding_color: JAnimColor = BLACK, surrounding_alpha: float = 0.5, font: str | Iterable[str] = [], depth: float = -100000.0, **kwargs) → TimeRange

subtitle(text: str | Iterable[str], range: TimeRange, **kwargs) → TimeRange

添加字幕

• 文字可以传入一个列表，纵向排列显示

• 可以指定在当前位置往后 delay 秒才显示

• duration 表示持续时间

• scale 表示对文字的缩放，默认为 0.8，可以传入列表表示对各个文字的缩放

• use_typst_text 表示是否使用 TypstText，可以传入列表表示各个文字是否使用

返回值表示显示的时间段

place_subtitle(subtitle: Text | TypstText, range: TimeRange) → None

被 subtitle() 调用以将字幕放置到合适的位置：

• 对于同一批添加的字幕 [a, b]，则 a 放在 b 的上面

• 如果在上文所述的 [a, b] 仍存在时，又加入了一个 c，则 c 放在最上面

has_subtitle() → bool

class ItemAppearance(item: Item, aligner: TimeAligner)

基类：object

包含与物件显示有关的对象

• self.stack 即 AnimStack 对象

• self.visiblility 是一个列表，存储物件显示/隐藏的时间点 - 列表中偶数下标（0、2、...）的表示开始显示的时间点，奇数下标（1、3、...）的表示隐藏的时间点 - 例如，如果列表中是 [3, 4, 8]，则表示在第 3s 显示，第 4s 隐藏，并且在第 8s 后一直显示 - 这种记录方式是 Timeline.is_visible()、Timeline.show()、Timeline.hide() 运作的基础

• self.renderer 表示所使用的渲染器对象

is_visible_at(t: float) → bool

在 t 时刻，物件是否可见

render(data: Item) → None

class ItemAppearancesDict(time_aligner: TimeAligner)

基类：defaultdict[Item, ItemAppearance]

track(item: Item) → None

使得 item 在每次 forward 和 play 时都会被自动调用 detect_change()

track_item_and_descendants(item: Item, *, root_only: bool = False) → None

相当于对 item 及其所有的后代物件调用 track()

detect_changes_of_all() → None

检查物件的变化并将变化记录为 Display

detect_changes(items: Iterable[Item]) → None

检查指定的列表中物件的变化，并将变化记录为 Display

（仅检查自身而不包括子物件的）

compute_item(item: T, as_time: float, readonly: bool) → T

另见 compute()

item_current(item: T, *, as_time: float | None = None, root_only: bool = False) → T

另见 current()

is_visible(item: Item) → bool

判断特定的物件目前是否可见

另见：show()、hide()

is_displaying(item: Item) → bool

show(*roots: Item, root_only=False) → None

显示物件

hide(*roots: Item, root_only=False) → None

隐藏物件

hide_all() → None

隐藏显示中的所有物件

cleanup_display() → None

visible_items() → list[Item]

add_additional_render_calls_callback(t_range: TimeRange, func: RenderCallsFn) → None

get_construct_lineno() → int | None

得到当前在 construct() 中执行到的行数

get_lineno_at_time(time: float)

根据 time 得到对应执行到的行数

debug(item: Item, msg: str | None = None) → None

将物件的动画栈显示在时间轴中

小技巧

显示在时间轴中的一个黄色扁条表示在哪些区段中物件是可见的

警告

有些动画是覆盖性的，例如直接数据改变（Display） 和 .anim （MethodTransform），不要因为没有看到预期的栈结构而感到困惑

static fmt_time(t: float) → str

dbg_time(ext_msg: str = '') → None

class janim.anims.timeline.SourceTimeline(*args, **kwargs)

基类：Timeline

与 Timeline 相比，会在背景显示源代码

source_object() → object

build(*, quiet=False, hide_subtitles=False, show_debug_notice=False) → BuiltTimeline

构建动画并返回

class janim.anims.timeline.BuiltTimeline(timeline: Timeline)

基类：object

运行 Timeline.build() 后返回的实例

property cfg: Config | ConfigGetter

get_audio_samples_of_frame(fps: float, framerate: int, frame: int, *, count: int = 1) → ndarray

提取特定帧的音频流

current_camera_info() → CameraInfo

render_all(ctx: Context, global_t: float, *, blend_on: bool = True) → bool

渲染所有可见物件

capture(global_t: float, *, transparent: bool = True) → Image

to_item(**kwargs) → TimelineItem

使用该方法可以在一个 Timeline 中插入另一个 Timeline

例如：

class Sub1(Timeline):
    def construct(self):
        text = Text('text from Sub1')
        text.points.shift(UP)
        self.play(
            Rotate(text, TAU, about_point=LEFT * 2),
            duration=4
        )


class Sub2(Timeline):
    def construct(self):
        text = Text('text from Sub2')
        text.points.shift(DOWN)
        self.play(
            Rotate(text, TAU, about_point=RIGHT * 2),
            duration=4
        )


class Test(Timeline):
    def construct(self):
        tl1 = Sub1().build().to_item().show()
        tl2 = Sub2().build().to_item().show()
        self.forward_to(tl2.end)

这个例子中，在 Test 中插入了 Sub1 和 Sub2

额外参数：

• delay: 延迟多少秒开始该 Timeline 的播放

• first_frame_duration: 第一帧持续多少秒

• keep_last_frame: 是否在 Timeline 结束后仍然保留最后一帧的显示

to_playback_control_item(**kwargs) → TimelinePlaybackControlItem

使用该方法可以在一个 Timeline 中插入另一个 Timeline

并且与 Video 类似，可以使用 start、stop 以及 seek 控制播放进度

例：

class Sub(Timeline):
    def construct(self):
        self.play(
            ItemUpdater(
                None,
                lambda p: Text(f'{p.global_t:.2f}')
            ),
            duration=8
        )


class Test(Timeline):
    def construct(self):
        sub = Sub().build().to_playback_control_item().show()
        sub.start()
        self.forward(2)
        sub.start(speed=0.1)
        self.forward(2)
        sub.seek(0).start(speed=4)
        self.forward(2)

注意：在默认情况下未开始播放，需要使用 start 以开始播放

额外参数：

• keep_last_frame: 是否在 Timeline 结束后仍然保留最后一帧的显示

class janim.anims.timeline.TimelineItem(built: BuiltTimeline, *, delay: float = 0, first_frame_duration: float = 0, keep_last_frame: bool = False, **kwargs)

基类：Item

详见 BuiltTimeline.to_item()

class TIRenderer

基类：Renderer

render(item: TimelineItem)

renderer_cls

TIRenderer 的别名

start() → Self

从当前时刻开始播放子时间轴，在此时刻之前保持显示第一帧

property end: float

class janim.anims.timeline.PlaybackControl(*args, loop: bool = False, **kwargs)

基类：object

start(*, speed: int = 1) → Self

stop() → Self

seek(t: float) → Self

compute_time(t: float, total: float | None = None) → float

class janim.anims.timeline.TimelinePlaybackControlItem(built: BuiltTimeline, *, keep_last_frame: bool = False, **kwargs)

基类：PlaybackControl, Item

详见 BuiltTimeline.to_playback_control_item()

class TPCIRenderer

基类：Renderer

render(item: TimelinePlaybackControlItem)

renderer_cls

TPCIRenderer 的别名