mirror of
https://github.com/iluvcapra/ptulsconv.git
synced 2025-12-31 17:00:46 +00:00
Reorganized docs into folders
This commit is contained in:
Jamie Hardt
74
docs/source/user/cli_reference.rst
Normal file
74
docs/source/user/cli_reference.rst
Normal file
@@ -0,0 +1,74 @@
|
||||
Command-Line Reference
|
||||
======================
|
||||
|
||||
Usage Form
|
||||
-----------
|
||||
|
||||
Invocations of ptulsconv take the following form:
|
||||
|
||||
ptulsconv [options] IN_FILE
|
||||
|
||||
|
||||
Flags
|
||||
-----
|
||||
|
||||
`-h`, `--help`
|
||||
Show the help message.
|
||||
|
||||
`f FMT`, `--format=FMT`
|
||||
Select the output format. By default this is `doc`, which will
|
||||
generate :ref:`ADR reports<adr-reports>`.
|
||||
|
||||
The :ref:`other available options<alt-output-options>`
|
||||
are `raw` and `tagged`.
|
||||
|
||||
|
||||
Informational Options
|
||||
"""""""""""""""""""""
|
||||
|
||||
These options display information and exit without processing any
|
||||
input documents.
|
||||
|
||||
`--show-formats`
|
||||
Display information about available output formats.
|
||||
|
||||
`--show-available-tags`
|
||||
Display information about tags that are used by the
|
||||
report generator.
|
||||
|
||||
|
||||
.. _alt-output-options:
|
||||
|
||||
Alternate Output Formats
|
||||
------------------------
|
||||
|
||||
.. _raw-output:
|
||||
|
||||
`raw` Output
|
||||
""""""""""""
|
||||
|
||||
The "raw" output format is a JSON document of the parsed input data.
|
||||
|
||||
The document is a top-level dictionary with keys for the main sections of the text export: `header`,
|
||||
`files`, `clips`, `plugins`, `tracks` and `markers`, and the values for these are a list of section
|
||||
entries, or a dictionary of values, in the case of `header`.
|
||||
|
||||
The text values of each record and field in the text export is read and output verbatim, no further
|
||||
processing is done.
|
||||
|
||||
.. _tagged-output:
|
||||
|
||||
`tagged` Output
|
||||
"""""""""""""""
|
||||
|
||||
The "tagged" output format is also a JSON document based on the parsed input data, after the additional
|
||||
step of processing all of the :ref:`tags<tags>` in the document.
|
||||
|
||||
The document is a top-level array of dictionaries, one for each recognized ADR spotting clip in the
|
||||
session. Each dictionary has a `clip_name`, `track_name` and `session_name` key, a `tags` key that
|
||||
contains a dictionary of every parsed tag (after applying tags from all tracks and markers), and a
|
||||
`start` and `end` key. The `start` and `end` key contain the parsed timecode representations of these
|
||||
values in rational number form, as a dictionary with `numerator` and `denominator` keys.
|
||||
|
||||
|
||||
|
||||
129
docs/source/user/for_adr.rst
Normal file
129
docs/source/user/for_adr.rst
Normal file
@@ -0,0 +1,129 @@
|
||||
.. _adr-reports:
|
||||
|
||||
`ptulsconv` For ADR Report Generation
|
||||
=====================================
|
||||
|
||||
Reports Created by the ADR Report Generator
|
||||
-------------------------------------------
|
||||
|
||||
(FIXME: write this)
|
||||
|
||||
|
||||
Tags Used by the ADR Report Generator
|
||||
-------------------------------------
|
||||
|
||||
|
||||
Project-Level Tags
|
||||
""""""""""""""""""
|
||||
|
||||
It usually makes sense to place these either in the session name,
|
||||
or on a :ref:`marker <tag-marker>` at the beginning of the session, so it will apply to
|
||||
all of the clips in the session.
|
||||
|
||||
`Title`
|
||||
The title of the project. This will appear at the top
|
||||
of every report.
|
||||
|
||||
.. warning::
|
||||
`ptulsconv` at this time only supports one title per export. If you attempt to
|
||||
use multiple titles in one export it will fail.
|
||||
|
||||
`Supv`
|
||||
The supervisor of the project. This appears at the bottom
|
||||
of every report.
|
||||
|
||||
`Client`
|
||||
The client of the project. This will often appear under the
|
||||
title on every report.
|
||||
|
||||
`Spot`
|
||||
The date or version number of the spotting report.
|
||||
|
||||
|
||||
Time Range Tags
|
||||
"""""""""""""""
|
||||
|
||||
All of these tags can be set to different values on each clip, but
|
||||
it often makes sense to use these tags in a :ref:`time range<tag-range>`.
|
||||
|
||||
`Sc`
|
||||
The scene description. This appears on the continuity report
|
||||
and is used in the Director's logs.
|
||||
|
||||
`Ver`
|
||||
The picture version. This appears beside the spot timecodes
|
||||
on most reports.
|
||||
|
||||
`Reel`
|
||||
The reel. This appears beside the spot timecodes
|
||||
on most reports and is used to summarize line totals on the
|
||||
line count report.
|
||||
|
||||
|
||||
Line tags
|
||||
"""""""""
|
||||
|
||||
`P`
|
||||
Priority.
|
||||
|
||||
`QN`
|
||||
Cue number. This appears on all reports.
|
||||
|
||||
.. warning::
|
||||
`ptulsconv` will verify that all cue numbers in a given title are unique.
|
||||
|
||||
All lines must have a cue number in order to generate reports, if any lines
|
||||
do not have a cue number set, `ptulsconv` will fail.
|
||||
|
||||
|
||||
`CN`
|
||||
Character number. This is used to collate character records
|
||||
and will appear on the line count and in character-collated
|
||||
reports.
|
||||
|
||||
`Char`
|
||||
Character name. By default, a clip will set this to the
|
||||
name of the track it appears on, but the track name can be
|
||||
overridden here.
|
||||
|
||||
`Actor`
|
||||
Actor name.
|
||||
|
||||
`Line`
|
||||
The prompt to appear for this ADR line. By default, this
|
||||
will be whatever text appears in a clip name prior to the first
|
||||
tag.
|
||||
|
||||
`R`
|
||||
Reason.
|
||||
|
||||
`Mins`
|
||||
Time budget for this line, in minutes. This is used in the
|
||||
line count report to give estimated times for each character. This
|
||||
can be set for the entire project (with a :ref:`marker <tag-marker>`), or for individual
|
||||
actors (with a tag in the :ref:`track comments<tag-track>`), or can be set for
|
||||
individual lines to override these.
|
||||
|
||||
`Shot`
|
||||
Shot. A Date or other description indicating the line has been
|
||||
recorded.
|
||||
|
||||
|
||||
Boolean-valued ADR Tag Fields
|
||||
"""""""""""""""""""""""""""""
|
||||
|
||||
`EFF`
|
||||
Effort. Lines with this tag are subtotaled in the line count report.
|
||||
|
||||
`TV`
|
||||
TV line. Lines with this tag are subtotaled in the line count report.
|
||||
|
||||
`TBW`
|
||||
To be written.
|
||||
|
||||
`ADLIB`
|
||||
Ad-lib.
|
||||
|
||||
`OPT`
|
||||
Optional. Lines with this tag are subtotaled in the line count report.
|
||||
|
||||
91
docs/source/user/quickstart.rst
Normal file
91
docs/source/user/quickstart.rst
Normal file
@@ -0,0 +1,91 @@
|
||||
Quick Start
|
||||
===========
|
||||
|
||||
The workflow for creating ADR reports in `ptulsconv` is similar to other ADR
|
||||
spotting programs: spot ADR lines in Pro Tools with clips using a special
|
||||
code to take notes, export the tracks as text and then run the program.
|
||||
|
||||
|
||||
Step 1: Use Pro Tools to Spot ADR Lines
|
||||
---------------------------------------
|
||||
|
||||
`ptulsconv` can be used to spot ADR lines similarly to other programs.
|
||||
|
||||
#. Create a new Pro Tools session, name this session after your project.
|
||||
#. Create new tracks, one for each character. Name each track after a
|
||||
character.
|
||||
#. On each track, create a clip group (or edit in some audio) at the time you
|
||||
would like an ADR line to appear in the report. Name the clip after the
|
||||
dialogue you are replacing at that time.
|
||||
|
||||
|
||||
Step 2: Add More Information to Your Spots
|
||||
------------------------------------------
|
||||
|
||||
Clips, tracks and markers in your session can contain additional information
|
||||
to make your ADR reports more complete and useful. You add this information
|
||||
with *tagging*.
|
||||
|
||||
* Every ADR clip must have a unique cue number. After the name of each clip,
|
||||
add the letters "$QN=" and then a unique number (any combination of letters
|
||||
or numbers that don't contain a space). You can type these yourself or add
|
||||
them with batch-renaming when you're done spotting.
|
||||
* ADR spots should usually have a reason indicated, so you can remember exactly
|
||||
why you're replacing a particular line. Do this by adding the the text "{R="
|
||||
to your clip names after the prompt and then some short text describing the
|
||||
reason, and then a closing "}". You can type anything, including spaces.
|
||||
* If a line is a TV cover line, you can add the text "[TV]" to the end.
|
||||
|
||||
So for example, some ADR spot's clip name might look like:
|
||||
|
||||
Get to the ladder! {R=Noise} $QN=J1001
|
||||
"Forget your feelings! {R=TV Cover} $QN=J1002 [TV]
|
||||
|
||||
These tags can appear in any order.
|
||||
|
||||
* You can add the name of an actor to a character's track, so this information
|
||||
will appear on your reports. In the track name, or in the track comments,
|
||||
type "{Actor=xxx}" replacing the xxx with the actor's name.
|
||||
* Characters need to have a number (perhaps from the cast list) to express how
|
||||
they should be collated. Add "$CN=xxx" with a unique number to each track (or
|
||||
the track's comments.)
|
||||
* Set the scene for each line with markers. Create a marker at the beginning of
|
||||
a scene and make it's name "{Sc=xxx}", replacing the xxx with the scene
|
||||
number and name.
|
||||
|
||||
|
||||
Step 3: Export Tracks from Pro Tools as a Text File
|
||||
---------------------------------------------------
|
||||
|
||||
Export the file as a UTF-8 and be sure to include clips and markers. Export
|
||||
using the Timecode time format.
|
||||
|
||||
Do not export crossfades.
|
||||
|
||||
|
||||
Step 4: Run `ptulsconv` on the Text Export
|
||||
------------------------------------------
|
||||
|
||||
In your Terminal, run the following command:
|
||||
|
||||
ptulsconv path/to/your/TEXT_EXPORT.txt
|
||||
|
||||
`ptulsconv` will create a folder named "Title_CURRENT_DATE", and within that
|
||||
folder it will create several PDFs and folders:
|
||||
|
||||
- "TITLE ADR Report" 📄 a PDF tabular report of every ADR line you've spotted.
|
||||
- "TITLE Continuity" 📄 a PDF listing every scene you have indicated and its
|
||||
timecode.
|
||||
- "TITLE Line Count" 📄 a PDF tabular report giving line counts by reel, and the
|
||||
time budget per character and reel (if provided in the tagging).
|
||||
- "CSV/" a folder containing CSV documents of all spotted ADR, groupd by
|
||||
character and reel.
|
||||
- "Director Logs/" 📁 a folder containing PDF tabular reports, like the overall
|
||||
report except groupd by character.
|
||||
- "Supervisor Logs/" 📁 a folder containing PDF reports, one page per line,
|
||||
designed for note taking during a session, particularly on an iPad.
|
||||
- "Talent Scripts/" 📁 a folder containing PDF scripts or sides, with the timecode
|
||||
and prompts for each line, grouped by character but with most other
|
||||
information suppressed.
|
||||
|
||||
|
||||
130
docs/source/user/tagging.rst
Normal file
130
docs/source/user/tagging.rst
Normal file
@@ -0,0 +1,130 @@
|
||||
.. _tags:
|
||||
|
||||
Tagging
|
||||
=======
|
||||
|
||||
Tags are used to add additional data to a clip in an organized way. The
|
||||
tagging system in `ptulsconv` allows is flexible and can be used to add
|
||||
any kind of extra data to a clip.
|
||||
|
||||
Fields in Clip Names
|
||||
--------------------
|
||||
|
||||
Track names, track comments, and clip names can also contain meta-tags, or
|
||||
"fields," to add additional columns to the output. Thus, if a clip has the
|
||||
name:::
|
||||
|
||||
`Fireworks explosion {note=Replace for final} $V=1 [FX] [DESIGN]`
|
||||
|
||||
The row output for this clip will contain columns for the values:
|
||||
|
||||
|
||||
+---------------------+-------------------+---+----+--------+
|
||||
| Clip Name | note | V | FX | DESIGN |
|
||||
+=====================+===================+===+====+========+
|
||||
| Fireworks explosion | Replace for final | 1 | FX | DESIGN |
|
||||
+---------------------+-------------------+---+----+--------+
|
||||
|
||||
|
||||
These fields can be defined in the clip name in three ways:
|
||||
* `$NAME=VALUE` creates a field named `NAME` with a one-word value `VALUE`.
|
||||
* `{NAME=VALUE}` creates a field named `NAME` with the value `VALUE`. `VALUE`
|
||||
in this case may contain spaces or any chartacter up to the closing bracket.
|
||||
* `[NAME]` creates a field named `NAME` with a value `NAME`. This can be used
|
||||
to create a boolean-valued field; in the output, clips with the field
|
||||
will have it, and clips without will have the column with an empty value.
|
||||
|
||||
For example, if three clips are named:::
|
||||
|
||||
`"Squad fifty-one, what is your status?" [FUTZ] {Ch=Dispatcher} [ADR]`
|
||||
|
||||
`"We are ten-eight at Rampart Hospital." {Ch=Gage} [ADR]`
|
||||
|
||||
`(1M) FC callouts rescuing trapped survivors. {Ch=Group} $QN=1001 [GROUP]`
|
||||
|
||||
The output will contain the range:
|
||||
|
||||
|
||||
+----------------------------------------------+------------+------+-----+------+-------+
|
||||
| Clip Name | Ch | FUTZ | ADR | QN | GROUP |
|
||||
+==============================================+============+======+=====+======+=======+
|
||||
| "Squad fifty-one, what is your status?" | Dispatcher | FUTZ | ADR | | |
|
||||
+----------------------------------------------+------------+------+-----+------+-------+
|
||||
| "We are ten-eight at Rampart Hospital." | Gage | | ADR | | |
|
||||
+----------------------------------------------+------------+------+-----+------+-------+
|
||||
| (1M) FC callouts rescuing trapped survivors. | Group | | | 1001 | GROUP |
|
||||
+----------------------------------------------+------------+------+-----+------+-------+
|
||||
|
||||
|
||||
.. _tag-track:
|
||||
.. _tag-marker:
|
||||
|
||||
Fields in Track Names and Markers
|
||||
---------------------------------
|
||||
|
||||
Fields set in track names, and in track comments, will be applied to *each*
|
||||
clip on that track. If a track comment contains the text `{Dept=Foley}` for
|
||||
example, every clip on that track will have a "Foley" value in a "Dept" column.
|
||||
|
||||
Likewise, fields set on the session name will apply to all clips in the session.
|
||||
|
||||
Fields set in markers, and in marker comments, will be applied to all clips
|
||||
whose finish is *after* that marker. Fields in markers are applied cumulatively
|
||||
from breakfast to dinner in the session. The latest marker applying to a clip has
|
||||
precedence, so if one marker comes after the other, but both define a field, the
|
||||
value in the later marker
|
||||
|
||||
An important note here is that, always, fields set on the clip name have the
|
||||
highest precedence. If a field is set in a clip name, the same field set on the
|
||||
track, the value set on the clip will prevail.
|
||||
|
||||
|
||||
.. _tag-range:
|
||||
|
||||
Apply Fields to a Time Range of Clips
|
||||
-------------------------------------
|
||||
|
||||
A clip name beginning with "@" will not be included in the output, but its
|
||||
fields will be applied to clips within its time range on lower tracks.
|
||||
|
||||
If track 1 has a clip named `@ {Sc=1- The House}`, any clips beginning within
|
||||
that range on lower tracks will have a field `Sc` with that value.
|
||||
|
||||
|
||||
Combining Clips with Long Names or Many Tags
|
||||
--------------------------------------------
|
||||
|
||||
A clip name beginning with `&` will have its parsed clip name appended to the
|
||||
preceding cue, and the fields of following cues will be applied, earlier clips
|
||||
having precedence. The clips need not be touching, and the clips will be
|
||||
combined into a single row of the output. The start time of the first clip will
|
||||
become the start time of the row, and the finish time of the last clip will
|
||||
become the finish time of the row.
|
||||
|
||||
|
||||
Setting Document Options
|
||||
------------------------
|
||||
|
||||
.. note::
|
||||
Document options are not yet implemented.
|
||||
|
||||
A clip beginning with `!` sends a command to `ptulsconv`. These commands can
|
||||
appear anywhere in the document and apply to the entire document. Commands are
|
||||
a list of words
|
||||
|
||||
The following commands are available:
|
||||
|
||||
page $SIZE=`(letter|legal|a4)`
|
||||
Sets the PDF page size for the output.
|
||||
|
||||
font {NAME=`name`} {PATH=`path`}
|
||||
Sets the primary font for the output.
|
||||
|
||||
sub `replacement text` {FOR=`text_to_replace`} {IN=`tag`}
|
||||
Declares a substitution. Whereever text_to_replace is encountered in the
|
||||
document it will be replaced with "replacement text".
|
||||
|
||||
If `tag` is set, this substitution will only be applied to the values of
|
||||
that tag.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user