议定书1.2版
简介
mimoLive使用苹果的Quartz Composer技术和它的文件来做层。因为mimoLive需要告诉Quartz Composer文件一些环境参数，以及从他们那里读取结果，我们设计了一个协议，你必须遵循，以便利用mimoLive提供的所有功能。在下面，你可以找到关于这个协议的所有技术信息。
如果你想学习如何用Quartz Composer创建自定义层，请阅读 "为mimoLive创建客户层":en:pro:custom_layer:create_custom_layers。
财产
你可以在Quartz Composer中编辑协议，选择 编辑 ⇢ 编辑信息 (⌥⌘I)
| 命名 | 需要 | 类型 | 样本价值 |
|---|---|---|---|
| 类别 | 字符串 | ||
| 版权 | 字符串 | © 2016 MySoftwareCompany | |
| 描述 | 字符串 | 播放一个全屏输入 | |
| 名称 | 是 | 字符串 | 全屏播放器 |
| 已删除 tv_Categories | 字符串 | 背景幕布,全屏 | |
| tv_Debug | 布尔型 | ||
| tv_FileData_ 输入名称- | 数据 | (导入XML文件) | |
| tv_FileName_ 输入名称- | 字符串 | 排名.xml | |
| tv_HelpURL | 字符串 | ||
| tv_HiddenInputKeys | 阵列的字符串 | ||
| tv_InputLabel_ 输入名称- | 字符串 | 视频输入 | |
| tv_LayerIdentifier | 是 | 字符串 | com.example.layer.mylayer |
| tv_LayerVersion | 是 | 数字（实数） | 1.01 |
| tv_LayerPreview | 数据 | (导入PNG文件) | |
| tv_LayerProtocolVersion | 是 | 数字（实数） | 1 |
| tv_SortKey | 字符串 | ||
| tv_StepSize_ 输入名称- | 数字（实数） | 0.1 | |
| 已删除 tv_Tagline | 字符串 | 播放一个全屏输入 | |
| tv_UseAudioFromSource | 字符串 | tvIn_VideoSourceA | |
| tv_UnitLabel_ 输入名称- | 字符串 |
类别
类别通常是由Quartz composer设置的，对于mimoLive层来说不需要。关于mimoLive的类别请看 tv_Categories 而不是。
版权
版权通常是由Quartz作曲家设置的，对于mimoLive层来说不需要。
描述
Quartz Composer标准 - 保持3行左右的长度，以便在预览中很好地适应。
名称
这个名字会在mimoLive里面显示。使用一个简短和独特的名字来快速找到你的层。
协议
这个数组通常由Quartz composer设置，对于mimoLive层不需要。
tv_Categories
已删除
这些类别是用来分组和过滤图层的。目前，它们被忽略了，但它可能被再次激活。使用以下预定义类别的逗号分隔的列表或定义你自己的类别。
- "音频" - 提供使用音频源的可能性的层
- "叠加" - 叠加数据或图像的层：Lower Thirds，标题，标志，...
- "全屏" - 至少通过默认设置提供全屏的图层--例如动画、单一视频、天气图。
- "背景"--作为上面其他东西的背景/衬托的层。
- "文本"--提供某种文本显示的层，例如信用、Lower Thirds、标题等。
- "数据" - 显示数据的层，例如股票行情、篮球比分等。
- "图像" - 提供使用静态图像输入的显示方式的层
- "多视频" - 结合了至少两个来源的图层，可以在下面的图层之外增加至少一个来源，或者使用两个或更多来源。
- "三维" - 提供某种三维定位元素的层，例如：演示者。
- "段"--为单独的段提供定时动画的层，例如，数字升级Beitrag
- "效果" - 提供一些叠加效果的层，例如放大镜、聚光灯、缩放......。
- "演示" - 主要用于演示功能的图层，而不是提供一般有用的功能，例如，天气图，它只是显示德国的地图。
- "消费者" - 使用compositedlayersimage的层，例如视频切换器、缩放、演示者
- "生成器"--提供某种生成的输出的层，例如，动画。
- "调试" - 对调试有用的层，在最终产品中不可见。
tv_Debug
告诉应用程序，这个组合只能在调试环境下使用。
tv_FileData_
一个将被创建并写入文件的数据blob，用于创建图层时的文件输入。这适用于将在_TypeFilePath中提供的文本文件或图像输入的.mov文件。参见 tv_FileName_ .
tv_FileName_
的相应文件名。 tv_FileData_ .如果有一个tv_FileData_*输入，则需要。
tv_HelpURL
这个字符串可以存储一个有关于如何使用这个层的有用信息的URL。mimoLive会在每个层的信息弹出窗口中呈现一个"？"按钮。如果用户点击这个按钮，URL会被系统的默认互联网浏览器打开。
tv_HiddenInputKeys
在这个数组中，组合持有应该从用户界面上隐藏的输入键。
tv_InputLabel_
可用于在参数视图中为给定的输入键提供一个备用的名称标签。也可以用空字符串表示没有标签。工作原理与 tv_hide_ouput ，例如，协议输入名称必须完整（例如 "tv_InputLabel_tvIn_VideoSourceAImage"）。
tv_LayerIdentifier
为了识别，Boinx运送的成分和分类的不同版本。必须是唯一的。建议使用反向注解的域名。例如：com.mysoftware.layer.videofullscreen
tv_LayerVersion
用于匹配文档/应用程序中的不同版本的组合。主要版本号表示不兼容，与其他主要版本不匹配（例如，如果输入键的名称改变，你需要增加主要版本）。小版本号必须是向上兼容的，并且每次迭代都可以增加0.001。例如，必须确保从1.0层为1.013层加载设置，必须看起来完全一样，这意味着新的键如果存在，需要有一个默认值，不显示它们或等同于前一个版本的外观。
tv_LayerPreview
用于在图层列表中预览一个图层的图像数据。这可以提供一个比默认的快速预览更好的体验。预览图像应该是256×256像素。
tv_LayerProtocolVersion
为了将来向后兼容，如果mimoLive大幅改变协议。目前必须设置为1。
tv_SortKey
定义了mimoLive中的层的排序。所以你可以根据使用的概率对过滤器进行排序。目前，使用2个大写字母的方案，例如："BM"、"DE"、"DM "等。注意：目前这个功能还没有使用，但将来会使用。
tv_StepSize_
可以用来为点动轮提供一个自定义的StepSize--然后一个像素的鼠标移动对应于这个变化量（也是+/-点击）。
tv_Tagline
已删除
一行字符串，将显示在图层存储库的信息弹出窗口。
tv_UseAudioFromSource
mimoLive目前只能在用户界面上显示一个音频控制。这个属性告诉它什么输入键是要控制的。填入完整的对应输入键。(为了向后兼容，这个字段也接受 "A"、"B "或 "C"，它们被翻译成tvIn_VideoSourceAImage、tvIn_VideoSourceBImage 或 tvIn_VideoSourceCImage。如果不提供 mimoLive 假设没有音频将被用于此层。
tv_UnitLabel_
可用于提供一个单位标签，例如参数视图中给定的输入键的 "pt"。尽量保持简短。有助于传达输入的含义。Boinx单位输入将自动获得 "px "标签。
输入
| 命名 | 类型 |
|---|---|
| tvIn_AccountTwitterConsumerKey | 字符串 |
| tvIn_AccountTwitterConsumerSecret | 字符串 |
| tvIn_AccountTwitterTokenKey | 字符串 |
| tvIn_AccountTwitterTokenSecret | 字符串 |
| tvIn_CompositedLayersImage | 图片 |
| tvIn_FrameCount | 索引 |
| tvIn_FrameDuration | 数量 |
| tvIn_CompositedLayersImage | 图片 |
| tvIn_In TransitionDirection | 索引 过渡方向 方向 |
| tvIn_In TransitionDuration | 数量 |
| tvIn_InTransitionType | 索引 过渡类型 类型 |
| tvIn_KeyboardModifierAlt | 布尔型 |
| tvIn_KeyboardModifierCommand | 布尔型 |
| tvIn_KeyboardModifierControl | 布尔型 |
| tvIn_KeyboardModifierFunction | 布尔型 |
| tvIn_KeyboardModifierShift | 布尔型 |
| tvIn_Obscured | 布尔型 |
| 电视直播 | 布尔型 |
| tvIn_OSVersion | 字符串 |
| tvIn_Out TransitionDirection | 索引 过渡方向 方向 |
| tvIn_Out TransitionDuration | 数量 |
| tvIn_OutTransitionType | 索引 过渡类型 类型 |
| tvIn_PreviewMode | 布尔型 |
| tvIn_Reset | 布尔型（信号） |
| tvIn_RuntimeIdentifier | 字符串 |
| tvIn_Shared_ | 任何价值类型 |
| tvIn_ShowDuration | 数量 |
| tvIn_ShowTimer | 数量 |
| tvIn_Switch | 布尔型（信号） |
| tvIn_TransitionDirection | 索引 过渡方向 方向 |
| tvIn_TransitionDuration | 数量 |
| tvIn_TransitionType | 索引 过渡类型 类型 |
| tvIn_UISnapColor | 颜色 |
| tvIn_VideoSourceA B C D | 图片 |
tvIn_AccountTwitterConsumerKey
tvIn_AccountTwitterConsumerSecret
tvIn_AccountTwitterTokenKey
tvIn_AccountTwitterTokenSecret
这四个AccountTwitter输入被用来从mimoLive Twitter账户偏好中输入登录数据。这些值与JSON补丁和OAuth补丁一起使用，以便从Twitter服务中读取数据。
tvIn_CompositedLayersImage
如果这个输入存在于一个构图中，并且有来自下面各层的内容，下面这些层的绘制结果将被送入这个输入。
tvIn_FrameCount
这个输入将得到启动mimoLive后的总渲染帧数。如果帧数因为渲染负荷太高而被放弃，帧数会跳过那些放弃的帧数。
tvIn_FrameDuration
帧的持续时间是指每次渲染之间的时间间隔，单位是秒。
tvIn_In TransitionDirection
一个将执行过渡方向的方向。
tvIn_In TransitionDuration
一个以秒为单位的值。 tvIn_InTransitionType 将被执行。
tvIn_InTransitionType
如果对一个让用户选择正在进行的过渡类型的图层有用。另外，见过渡类型类型。
tvIn_KeyboardModifierAlt
tvIn_KeyboardModifierCommand
tvIn_KeyboardModifierControl
tvIn_KeyboardModifierFunction
tvIn_KeyboardModifierShift
当用户在键盘上按下相应的修改键时，那些布尔输入字段将被设置为真。这个功能主要用于直接操作功能。请参考Apple Human用户指南行，看看在用户界面中哪个功能应该使用哪个修改键。
tvIn_Obscured
如果该层不需要渲染任何输出，这个输入被设置为 "true"，因为上面的层无论如何都会通过绘制全屏来掩盖它。这可以用来避免那些不可见但被设置为实时的图层的大量绘制。(例如，在Twitter层的情况下，即使被上面的另一个层遮挡，该层仍然被调用，并有机会保持与Twitter服务的互联网连接)。
电视直播
这个输入开始时的值是 "真"。一旦输入值为 "false"，构图就应该进行任何输出转换，然后在转换完成后设置其Done输出。然后，该组合将被停用。可能发生的情况是，应用程序在没有等待 "完成 "标志的情况下关闭了一个层。
tvIn_OSVersion
这个字符串输入将被设置为当前的OS X版本（例如，"版本10.11.2（Build 265341）"）。
tvIn_Out TransitionDirection
的一个值，以秒为单位。 tvIn_OutTransitionType 将被执行。另外，见过渡方向。
tvIn_Out TransitionDuration
的一个值，以秒为单位。 tvIn_OutTransitionType 将被执行。
tvIn_OutTransitionType
如果对一个让用户选择正在进行的过渡类型的图层有用。另外，见过渡类型类型。
tvIn_PreviewMode
可以用来告诉构图，它处于预览模式。
tvIn_Reset
有助于重置组合的逻辑。当一个图层从关闭状态切换到实时状态时，或者在设置和无设置之间切换时，这个标志被设置。 tvIn_Switch 可输入的信息。
tvIn_RuntimeIdentifier
帮助图层在预览和实时实例之间沟通。由mimoLive动态设置。
tvIn_Shared_
见 层与层之间共享价值 层与层之间的数值。
tvIn_ShowDuration
如果用户在 "显示设置 "中填写了显示持续时间，这个输入将有以秒为单位的值。
tvIn_ShowTimer
显示计时器将反映mimoLive文件的显示计时器，单位是秒。
tvIn_Switch
这个标志被设置，而不是 tvIn_Reset]]，当一个图层从一个设置切换到另一个设置而没有禁用该图层。如果这个输入不存在，[[#tvIn_Reset 当一个图层从一个设置切换到另一个设置时，不会禁用该图层。如果这个输入不存在，[[#tvIn_Reset]]将被设置，以保持与旧层的兼容性。
tvIn_TransitionDirection
一个方向，在这个方向上 过渡方向 将被执行。
tvIn_TransitionDuration
的一个值，以秒为单位。 tvIn_InTransitionType 将被执行。
tvIn_TransitionType
如果对一个让用户选择正在进行的过渡类型的图层有用。另外，见过渡类型类型。
tvIn_UISnapColor
为了保持UI的一致性，mimoLive提供了一个 "捕捉颜色"，当UI被捕捉到某个值时，可以在预览中画出指引（例如，在自定义显示模式下旋转Placer层时按住 "shift "键，当旋转角度捕捉到0、45或90度时，指引将以该颜色绘制）。
tvIn_VideoSource
一个层最多可以有8个动态视频源输入："A"、"B"、"C "等等。如果用户将视频源从源存储库拖到图层堆栈中，它们将由一个下降区表示。//注意：为了向后兼容，这些输入上的扩展名 "Image "被忽略了。
输入选项
对应的输入键
如果有一个视频输入键，下面的输入键也会相应地被填上信息：
(例如，"tvIn_VideoSourceA"->"tvIn_VideoSourceAName")
| 钥匙 | 类型 | 描述 |
|---|---|---|
| 音频增益 | 数量 | TBD |
| 音频水平0 | 数量 | 增益控制后的左声道电平，单位为db |
| 音频级别1 | 数量 | 增益控制后的右声道电平，单位为db |
| 音频电平0Raw | 数量 | 增益控制前的左声道电平，单位为分贝 |
| 音频级别1Raw | 数量 | 增益控制前的右声道电平，单位为db |
| 音频平移 | 数量 | TBD |
| 音频音量 | 数量 | TBD |
| 数据 | 结构 | 源的元数据的字典。目前，实现的键是"index" "duration" "title" "titleFallback" "artist" "album" "year" "fileReferenceIdentifier" |
| 命名 | 字符串 | 相关图像源的名称。可用于在预览中显示其名称或计算图层变体的默认名称。参见 tvOut_SettingName . |
| 剩余时间 | 数量 | 以秒为单位。将被提供给电影源。如果电影源是循环的（或任何其他源），则-1。 |
| 帐单状态 | 索引 | 连接源的理货状态，见 理算国家 国家 |
| 类型 | 索引 | 的价值 源类型 类型 |
分组输入
分组是在用户界面上提供的--为此，输入的前缀是相关的。语法工作原理如下 tvGroup___.请注意在组名后面有双下划线_ _，作为输入名称的分隔符。
为那些应该总是被隐藏的输入定义了一个特殊的组： tvGroup_Hidden_Inputs__。 这个组可以通过将mimoLive切换到调试模式在 debug|Debug偏好|调试首选项。一些层使用这些隐藏字段在 "预览实例 "和 "实时实例 "之间进行通信（例如，视频切换器层告诉预览实例哪个视频源是实时的）。
动态地隐藏输入
每一个协议输入都将在用户界面中被隐藏，如果 tvOut_hide_ 输出被设置为 "真"。这个值由应用程序观察，可以动态地改变。注意，你需要使用完整的输入名称，包括 "tvIn"（例如，使用输出的 tvOut_hide_tvIn_Text_TypeMultiline 为输入 tvIn_Text_TypeMultiline).
输出
| 命名 | 类型 |
|---|---|
| tvOut_Cursor | 字符串 |
| tvOut_Done | 布尔型（信号） |
| tvOut_hide_ | 布尔型 |
| tvOut_Opaque | 布尔型 |
| tvOut_SettingName | 字符串 |
| tvOut_Share_ | 任何类型 |
| tvOut_TimeRemaining | 数量 |
| tvOut_UseCompositedLayersImage | 布尔型 |
| tvOut_TallyState | 指南的索引 理算国家 国家 |
| tvSet_ | 要设置的输入类型 |
| tvSetSignal_ | 布尔型 |
| tvSetAudioVolume_ | 数量 |
| tvSetAudioVolumeSignal_ | 布尔型 |
tvOut_Cursor
该输出指定了鼠标指针在预览或程序输出视图上时的鼠标指针外观。请参考 苹果公司NSCursor类文档) 为有效值。mimoLive提供的其他鼠标指针是 "减 "和 "加"。
*从苹果的NSCursor常量中删除后缀"_Cursor "或 "Cursor"（例如，使用 "openHand "来获得一个张开手的鼠标指针）。
tvOut_Done
用来告诉下一层，这一层已经完成。参见 电视直播 为文件。
tvOut_hide_
可以用来动态地隐藏参数视图中的输入值。见 动态地隐藏输入 .
tvOut_Opaque
用来告诉应用程序，在这个层下面的层不必被绘制。默认为 "false"。这个值被任何包含阿尔法的连接源覆盖。
tvOut_SettingName
作曲可以根据一些输入为一个环境建议一个有用的名字。
tvOut_Share_
见 层与层之间共享价值 .
tvOut_TimeRemaining
允许应用程序显示一些大的定时器倒计时（例如，离电影结束还有5秒）。目前使用"-1 "表示没有剩余时间的信息，如果是循环播放的电影则使用"-2"。
tvOut_UseCompositedLayersImage
当使用下面的图层与过渡等时，用于优化性能。它告诉应用程序，该层目前需要输入合成层的图像。 mimoLive将在下一个渲染周期输入合成图像下面的层。如果 "tvOut_UseCompositedLayersImage "不存在，mimoLive假设图像下面的层应该总是被放进去。只有绘图优化，所有的媒体还是会被滚动。只在以下情况下使用 tvIn_CompositedLayersImage 是存在的。
tvOut_TallyState
这个输出层可以覆盖当前连接到该输入的源的自动理线状态。这对转换很有用，或者如果该源不用于输出，则可以关闭理货状态（例如，视频切换器使用3台摄像机，但每次只显示一台，所以它需要将未使用的源的理货状态设置为 "TVTallyStateOff"）。请参阅 理算国家 为理货员状态的列表。
tvSet_
在mimoLive中，一个层或过滤器可以操纵自己的参数。这主要是为了实现层变体预览中的直接操作功能（例如，如果用户在预览中拖动模拟时钟，该层会告诉mimoLive哪个输入键应该被改变为哪个值。然而，这个功能也被用来将实时数据从程序输出实例转移到预览实例，反之亦然（例如，在视频切换器层，程序输出实例告诉预览实例哪个视频源是当前实时的，预览实例可以告诉程序输出实例用户在屏幕上选择哪个视频源）。
为了利用这个功能，你需要有两个输出，与你要操作的输入字段相对应：在'tvSet_'中，你输出你想设置的新值，在'tvSetSignal_'中，你发出该值有效并被存储的信号。
tvSetSignal_
见 tvSet_ .
tvSetAudioVolume_
这个输出控制其相关音源（或视频源的音频）的音量。有效值是0=无声到1=满。每次要改变音频音量时，作品必须设置相应的 "tvSetAudioVolumeSignal_"。例如，如果该层有一个淡入的过渡，并且希望也能淡入音频，这就很有用。
tvSetAudioVolumeSignal_
层与层之间共享价值
一个图层可以向图层堆栈中高于自己的其他图层发送数据。这些数据被mimolive通过它的共享密钥保存到下一个渲染周期。如果一个图层被多次使用（或者在不同的图层中使用相同的共享键），数据会被上面的图层覆盖。要设置这个共享数据，请使用 "tvOut_Share_"输出。你可以存储任何QuartzComposer数据类型，但建议使用结构体，因为你只需要一个输出就可以得到多个值。在接收层一侧，你需要一个相应的 "tvIn_Shared_"输入，其数据类型也是如此。请注意，接收层需要在层栈中的发送层之上。
如果你在多个图层中需要相同的数据（例如游戏中的主队和客队对手的名字），那么数值的共享就很有用。
类型定义（又称命名公约）。
| 钥匙 | 类型 | 描述 |
|---|---|---|
| *_TypeAudio | 图片 | 这是一个非常特殊的情况：一个_TypeAudio只能指定包含音频的源（例如电影源、视频源或仅有音频的源）。该层将通过"_TypeAudioAudioLevel0 "和"_TypeAudioAudioLevel1 "输入获得对这个源的控制（在未来），以及左右声道的音频音量值。 |
| *_TypeBoinxX | 数量 | 以Boinx X坐标输入的数字--例如，-1是第一个像素，1是当前屏幕尺寸的最后一个像素。 将以像素为单位呈现给用户。 |
| *_TypeBoinxY | 数量 | 以Boinx Y坐标输入的数字--例如，-1是底部像素，1是当前屏幕尺寸的最顶部像素。 将以像素为单位呈现给用户。 |
| *_TypeDirectoryPath | 字符串 | 导致用户界面中出现 "选择...... "按钮，也许还显示一个路径控件 |
| *_TypeDuration | 数量 | 以秒为单位的时间 - 将以分：秒为单位显示，并可以获得一个自定义的用户界面 |
| *_TypeFilePath | 字符串 | 导致用户界面中出现 "选择...... "按钮，也许还显示一个路径控件 |
| *_TypeFontBoinxSize | 字符串 | 以Boinx Y坐标表示的字体大小（例如，2是全屏高度），见以下说明 |
| *_TypeFontColor | 颜色 | 常规颜色输入，用于指定文本颜色，见以下说明 |
| *_TypeFontName | 字符串 | 这将导致出现一个字体选择器，见下面的注释 |
| *_TypeMultiline | 字符串 | 一个多行文本字段，允许输入返回值 |
| *_TypePassword | 字符串 | 显示一个密码文本框。重要的是：密码本身是以纯文本形式存储的，在文件中是可读的！ |
| *_TypeSignal | 布尔型 | 对于单帧脉冲信号，使用脉冲或观察者补丁。 |
*如果_TypeFontName、_TypeFontBoinxSize和_TypeFontColor字段具有相同的基础标签，它们将在图层参数视图中合并为一个字体选择器UI元素。
过滤器模板
这些输入和属性是特定的，如果你正在创建一个Quartz Composition来作为mimoLive的图像过滤器使用。前面的大部分定义也适用于过滤器。
滤波器输入
以下输入字段是Quartz Composer对一个过滤器组成的要求：
| 命名 | 类型 | 描述 |
|---|---|---|
| _protocolInput_PreviewMode | Bool | 可以用来告诉构图，它处于预览模式中 |
| _protocolInput_X | 数量 | 始终为0。 |
| _protocolInput_Y | 数量 | 始终为0。 |
过滤器属性
以下属性由 mimoLive 定义。 tv_FilterIdentifier 和 tv_FilterVersion 是处理过滤器和其更新路径与较新版本的需要：
| 命名 | 类型 | 样本价值 | 描述 |
|---|---|---|---|
| tv_FilterIdentifier | 字符串 | com.boinx.mimoLive.layer.placer | 为了识别，Boinx运送的成分和分类的不同版本 |
| tv_FilterVersion | 数字（双数） | 1 | 用于匹配一个文件/应用程序中的不同版本的成分。主要版本号表示不兼容，不与其他主要版本匹配。次要版本号必须是向上兼容的，并且每次迭代都会递增0.001。例如，必须确保从1.0层加载到1.013层的设置必须看起来完全一样，这意味着如果存在新的键，需要有一个不显示它们的默认值，或者等同于以前版本的外观。 |
| tv_FilterOutputIsOpaque | BOOL | 决定一个过滤器的输出是否是不透明的。默认为NO |
枚举
Quartz Composer的索引类型允许命名索引。它们可以在Quartz Composer编辑器中通过在索引模式下添加一个输入分割器来编辑。
来源类型
来源将是以下数值之一
- 0 - 图片
- 1 - 电影，一部电影会有一个剩余时间
- 2 - 照相机，也可能是一种构成
过渡方向
你可以定义你自己的方向。运送的各层使用的是以下数值。
- 无
- 左边
- 对
- 上
- 下降
过渡类型
你可以定义你自己的过渡类型。这里有一些有用的例子值。
- 溶解
- 擦拭
理算国家
有几个为视频源定义的Tally状态，将在用户界面和Tally Light配套应用中体现。
- 0 = TVTallyStateOff
- 10 = TVTallyStateInUse
- 20 = TVTallyStatePreview
- 30 = TVTallyStateEffect
- 40 = TVTallyStateProgram