媒体记录手册

工作流程

用户提交调试信息

基本上：

获取样本

运行脚本

提交该目录

有关这一点，请参阅 tools/ffmpeg/readme_run_tests.txt 。

在pyglet ffmpeg子系统中更改代码

准备像在README_RUN_Tests.txt中一样，可以选择安装库Bokeh(http://bokeh.pydata.org/en/latest/index.html)以获得可视化支持。

基本流程如下：

初始化活动会话子系统：设置环境变量 pyglet_mp_samples_dir 设置为所需的Samples_dir。

记录具有初始状态的会话：：

configure.py new <session> [playlist]
run_test_suite.py

请遵循以下工作流程

while True:
    edit code
    commit to hg
    record a new session:
        configure.py new <new session> [playlist]
        run_test_suite.py
    look at the last session reports in samples_dir/session/reports
    especially 00_summary.txt, which shows defects stats and list condensed
        info about any sample failing;
    then to look more details look at the individual reports.
    compare with prev sessions if desired:
        compare.py <session1> <session2>

    render additional reports:
        report.py sample

    or visualize the data collected with:
        bokeh_timeline.py sample

    if results are as wanted, break
done, you may want to delete sessions for intermediate commits

可以返回前一届会议，要求提交更多报告：

configure.py activate <session>
report.py ...

您可以使用：：列出当前Samples_dir的已知会话

configure.py list

重要

所有这些调试机制都依赖于对媒体播放器相关状态的详细而准确的捕获，当前的捕获位置是/media_player.py和pyglet.media.player。

在这些模块中的修改可能需要在pyglet/media/Sources/Instrumentation.py中进行匹配的修改，并进一步传播到其他模块。

更改Piglet ffmpeg的调试代码

对于调试代码的初始调试，需要消除拼写错误和小错误，为每个run_test_suite.py运行创建一个新会话可能不太方便。

旗帜 dev_debug 在会话配置文件中可以设置为TRUE；这将允许重写会话。

请记住，一些原始数据可能会过时或具有误导性：

在会话创建时捕获的文件(当前为pyglet.info和pyglet_changeset)

收集的崩溃信息(不会看到新的崩溃)

如果media_player.py在执行任何写入之前崩溃，则状态记录将是前一次记录。

使用陈旧原始数据的报告显然会报告陈旧数据。

因此，尽可能快地切换到正常工作流是一个好主意(只需创建新会话并删除特殊会话)。

会话

如果 playlist_file 则Samples_dir中的所有文件(扩展名为“.dbg”、“.htm”、“.html”、“.json”、“.log”、“.pkl”、“.py”、“.txt”)将成为隐式播放列表；Samples_dir的子目录将 not 被探索。

如果一个 playlist_file ，那么它应该每行包含一个样例名称；将执行健全性检查，以确保没有使用列入黑名单的扩展名，并且样例存在于Samples_dir中。

一旦 playlist_file 用于 configure.py new 将副本写入会话原始数据目录，并且该副本将是会话的权威播放列表； playlist_file 如果需要，可以将其删除。

指定播放列表在开发中非常有用，可以将测试限制为与正在工作的功能或问题相关的样本。

会话名称将用于创建Samples_dir子目录来存储测试结果，因此它应该不同于以前的会话名称，并且不能包含斜杠。 / ，反斜杠 \ 或目录名称中禁止的字符。

活动会话

大多数命令和子命令都针对当前活动的会话。

会话在以下情况下变为活动状态

一个 configure.py new session [playlist] 已发布

一个 configure.py activate session 已发布

当前实现依赖于两条数据来确定活动会话

环境变量 pyglet_mp_samples_dir 指定Samples_dir，这是所有媒体样本所在的目录。在当前路径模式下，还将存储会话数据，每个会话一个子目录。

一份文件 activation.json 在Samples_dir中存储当前活动会话的名称。

请注意，第二个命令排除了并行运行两个针对同一sampledir中的两个不同会话的命令。

活动会话的概念加上强制路径模式避免了在每次命令调用时提供路径的需要，从而减少了错误、文档和打字。

命令摘要

主要命令

它们是开发人员通常使用的

configure.py ， mp.py ：会话创建、激活、保护、状态和全部列出。

run_test_suite.py ：播放会话的样本，报告结果。

report.py ：为指定的样本生成指定的报告。

timeline.py ：将事件流转换为 media_player 状态，这对传递给其他软件很有用。

bokeh_timeline.py ：将为指定样本收集的数据可视化。

帮助器命令

不知何故，一件艺术品 run_test_suite.py 开发，可以帮助测试调试子系统。 run_test_suite.py 基本上就是 playmany.py + retry_crashed.py + summarize.py 。当试图改变的时候 run_test_suite.py 首先改编相关的帮助者会更容易。

playmany.py ：播放活动会话样本，记录播放过程中的媒体播放器状态。

retry_crashed.py ：再次播放经常崩溃的样本，希望获得不崩溃的录音。其动机是在Ubuntu上进行早期测试，有时(但不总是)样例会使媒体播放器崩溃。

summarize.py ：使用前两个命令产生的原始数据编制一些报告，旨在了解运行情况以及应该调查哪些样本。

数据目录布局

samples_dir/ : directory where the samples live, also used to store
               sessions data
    <session name>/ : directory to store session info, one per session,
                      named as the session.
        dbg/ : recording of media_player events captured while playing a
               sample, one per sample, named as sample.dbg; additional
               versioning info, other raw data collected.
            _crashes_light.pkl : pickle with info for retry crashed
            _pyglet_hg_revision.txt
            _pyglet_info.txt
            _samples_version.txt
            _session_playlist.txt
            <one .dbg file per sample in the session playlist, named sample.dbg>
        reports/ : human readable reports rendered from the raw data (.txt),
                   visualizations (.html), intermediate data used by other
                   tools(.pkl)
        configuration.json : session configuration info, mostly permissions
    activation.json : holds the name of current active session
    <sample> : one for each sample

如果出现以下情况，则会将samples_dir的子目录检测为会话目录：

它是会话目录的直接子目录

它有一个 configuration.json 文件

政策：

应该很难重写.dbg文件(媒体播放器状态的记录)

考虑一下dev分析用户发送的数据。

代码布局和约定

新出现的责任分离是这样的

脚本(命令)

结构如下：

用途 if __main__ 允许用作模块的习惯用法(测试、共享)

sysargs_to_mainargs() ： sys.argv 翻译为 main 帕拉姆斯

main(...)

参数验证和转换为适当的代码实体(使用模块 fs )。

将异常转换为打印(使用模块 mpexceptions )

实现命令目标的短链实例化/函数调用，这里没有逻辑或计算。

其他函数和类：特定于该命令的代码，将尽可能多的委托给模块。

当两个脚本使用一些相关但不相同的功能时，可以将这些部分移动到另一个模块。示例：一开始 summarize 有收集缺陷统计数据的代码，后来，当 compare 被写入时，模块 extractors 已添加，并且缺陷集合统计信息代码移至该模块。

如果脚本B需要未更改的脚本A功能的子集，它将导入A并使用它需要的功能。例如 retry_crashed ，将调用 playmany 。

由于最后一点，一些脚本也将被列为模块。

模块

buffered_logger

在播放媒体播放器时累积调试事件，在示例的播放结束时保存

仪器仪表

定义修改媒体播放器状态的事件。定义哪些事件是潜在缺陷。提供从记录的数据中提取信息的低级支持。

对于这里的新代码，继续只接受和返回数据结构，不接受路径或文件。

财政司司长

应将实体到会话目录的路径构建委托给 fs.PathServices 。开始时会话的创建、激活和管理 fs 。版本捕获在模块开始时处理 fs 。要在结束时加载-保存的实用程序函数 fs 。

虽然没有一个 Session 对象，实际上，该代码通过处理 fs.PathServices 举个例子。

萃取器

分析媒体播放器记录，以代表记者建立特定信息。用途 instrumentation 以获取有关播放示例时看到的媒体播放器状态序列的输入数据。定义对象类型以收集有关重播的一些特定信息。

报告

格式化为在其他地方捕获/生成的文本信息。

MP异常

定义由ffmpeg调试子系统中的代码生成的异常。

同时充当模块的脚本

时间表

将媒体播放器的调试信息呈现为更适合在电子表格或其他软件中进行后处理的格式，特别是为了获得数据可视化。(用于 bokeh_timeline.py )

玩得很多

生成媒体播放器调试录音。以带超时的子进程的形式运行python脚本(由retry_crashed.py使用)。

详细命令

bokeh_timeline.py

用法：：

bokeh_timeline.py sample

使用bokeh以图形方式呈现媒体播放器的内部状态。

论点：

sample: sample to report

输出将写入会话的输出目录中 reports/sample.timeline.html 。

请注意，可以使用鼠标滚轮实时缩放绘图，但您必须单击看起来扭曲的按钮 OP ；它还可以使用鼠标拖动进行平移。

示例：：

bokeh_timeline.py small.mp4

将输出写入 report/small.mp4.timeline.html 。

compare.py

用法：：

compare.py --reldir=relpath other_session

生成将活动会话与Other_Session进行比较的报告。

输出到 samples_dir/relpath/comparison_<session>_<other_session>.txt 。

configure.py

用法：：

configure.py subcommand [args]

子命令：

new session [playlist] : Creates a new session, sets it as the active one
activate session : activates a session
deactivate : no session will be active
protect [target]: forbids overwrite of session data
status : prints configuration for the active session
help [subcommand] : prints help for the given subcommand or topic
list : list all sessions associated the current samples_dir

创建和管理pyglet媒体播放器调试会话配置。

大多数命令和子命令都需要环境变量 pyglet_mp_samples_dir 设置为媒体样本所在的目录。

该配置存储执行其他命令时使用的一些值，主要是保护状态。

此命令可以调用为 configure.py 或 mp.py ，他们也是这样做的。

mp.py

的别名 configure.py

playmany.py

用法：：

playmany.py

使用媒体播放器播放一系列示例并记录调试信息。

会话必须处于活动状态，请参见命令 configure.py 如果活动配置不允许DBG覆盖，则不会执行任何操作。

如果在创建会话时提供了播放列表，则只会播放播放列表中的样本，否则 samples_dir 。

report.py

用法：：

report.py sample report_name

从播放示例时记录的调试信息生成报告。

论点：

sample: sample to report
report_name: desired report, one of
    "anomalies": Start, end and interesting events
    "all": All data is exposed as text
    "counter": How many occurrences of each defect

该报告将写入会话的输出目录中 reports/sample.report_name.txt 。

示例：：

report anomalies small.mp4

将撰写这份报告 anomalies 至 report/small.mp4.anomalies.txt 。

可用报告的权威列表来自 reports.available_reports

retry_crashed.py

用法：：

retry_crashed.py [--clean] [max_retries]

检查收集的原始数据，以获取上次播放时崩溃的样本列表。然后它重放这些样本，为它们记录新的原始数据。

重复该过程，直到所有样本都具有没有崩溃的记录或者播放了仍在崩溃的样本 max_tries 此命令中运行的次数。

请注意，只有在上次运行中记录为崩溃的样本才会被重试。

配置必须处于活动状态，请参见命令 configure.py 。

除了更新的调试记录外，还构建并保存状态：

total_retries: total retries attempted, including previous runs
sometimes_crashed: list of samples that crashed one time but later
                   completed a play
always_crashed: list of samples that always crashed

选项：

--clean: discards crash data collected in a previous run
max_retries: defaults to 5

run_test_suite.py

用法：：

run_test_suite.py [samples_dir]

使用pyglet媒体播放器播放媒体示例，记录播放的每个示例的调试信息，并编写有关捕获的数据的报告。

论点：

samples_dir: directory with the media samples to play

如果未提供Samples_dir，则活动会话是目标。如果在创建会话时指定了显式播放列表，则只播放播放列表中的样本，否则将播放Samples_dir中的所有样本。

If sample_dir is provided, a session named testrun_00 (_01, _02, ... if that name was taken) will be created, with no explicit playlist, and then the command operates as in the previous case.

输出文件将放入：

samples_dir/session/dbg : binary capture of media_player events, other raw
                          data captured
samples_dir/session/reports : human readable reports

备注

此脚本将拒绝覆盖现有的 test_run results 。

输出文件将放入子目录中：

samples_dir/test_run/dbg

每个样本都将生成一个 sample.dbg 存储播放示例时看到的播放器调试事件序列的文件。它只是一个元组列表的泡菜，每个元组都是一个事件。它不是供人类直接使用的，而是运行一些分析器来提供有用的报告。

A crash_retries.pkl 文件，一份泡菜 (total_retries, sometimes_crashed, still_crashing) <-> (int, set, set) 。

A pyglet.info 在创建会话时捕获以跟踪硬件和软件。

在创建会话时捕获的pygletHG修订。

samples_dir/test_run/reports

人类可读的输出，在命令中描述 summarize.py

稍后，用户可以生成将存储在此目录中的可视化和其他报告

summarize.py

用法：：

summarize.py

汇总了使用收集的会话信息 playmany 和 retry_crashes 。

配置必须处于活动状态，请参见命令 configure.py 。

如果在创建会话时提供了播放列表，则只播放播放列表中的样本，否则将播放Samples_dir中的所有文件。

生成人类可读的报告，从.dbg文件构建。

输出将在

samples_dir/test_run/reports

该目录中的文件将是

00_summary.txt ，它提供：

所有样本的基本缺陷统计信息

每个非完美样本游戏的段落，以及观察到的每个异常情况的计数

03_pyglet_info.txt ， pyglet.info 给出操作系统、Python版本等的输出(在创建会话时捕获)。

04_pyglet_hg_revision.txt 如果从repo克隆运行，则为非写入；如果没有repo(在创建会话时捕获)，则为非写入。

sample_name.all.txt 和 sample_name.anomalies.txt 对于每一个表现不完美的样本。

sample_name.all.txt 中包含所有信息。 sample_name.dbg 以人类可读的形式，即球员在比赛中的内部事件的顺序。

sample_name.anomalies.txt 是简化版的 .all 。变体：不显示正常事件，仅显示异常。

timeline.py

用法：：

timeline.py sample [output_format]

将媒体播放器的调试信息呈现为更适合在电子表格或其他软件中进行后处理的格式，特别是为了获得数据可视化。

请参阅手册中的输出详细信息。

论点：

sample: sample to report
output_format : one of { "csv", "pkl"}, by default saves as .pkl (pickle)

输出将写入会话的输出目录中 reports/sample.timeline.[.pkl or .csv] 。

示例：：

timeline.py small.mp4

将输出写入 report/small.mp4.timeline.pkl 。

备注

.csv 示例当前未实现。

样本

样本应该很小，目前我建议任意设置2MB 2分钟的限制。Samples目录包含一个 _sources.txt 上面列出了每个样本的来源。

警告：

样品未经“认证符合规格”。

在可能的情况下，应使用非ffmpeg软件播放样品，以便偶然确认格式良好

*.mp4 ， *.3gp 与Windows Media Player for Win7配合使用效果良好

*.ogv ， *. webm 与Firefox 54.0配合良好

*.flv ， *.mkv 使用VLC媒体播放器播放效果很好，但VLC使用ffmpeg

当然，样本集将随着时间的推移而精炼。

PyCharm注意到

为 examples/video_ffmpeg 模块可见性和代码完成，该目录应该是pycharm设置|‘项目结构’中的‘内容根’；由于项目根不能嵌套，所以pyglet工作副本不能是‘内容根’，所以我删除了它；我还添加了Working_Copy/pyglet作为另一个‘内容根’，所以pycharm在库中也发挥得很好。这款带有PY 2017.2的