mirror of
https://github.com/iluvcapra/ptulsconv.git
synced 2025-12-31 08:50:48 +00:00
Restructuring documenation
Swiching to readthedocs.io
This commit is contained in:
Jamie Hardt
69
docs/source/conf.py
Normal file
69
docs/source/conf.py
Normal file
@@ -0,0 +1,69 @@
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# For the full list of built-in configuration values, see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
||||
|
||||
project = 'ptulsconv'
|
||||
copyright = '2022, Jamie Hardt'
|
||||
author = 'Jamie Hardt'
|
||||
release = 'Version 2'
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
|
||||
|
||||
extensions = [
|
||||
'sphinx.ext.autodoc',
|
||||
'sphinx.ext.todo',
|
||||
'sphinx.ext.coverage',
|
||||
'sphinx.ext.viewcode',
|
||||
'sphinx.ext.githubpages',
|
||||
]
|
||||
|
||||
templates_path = ['_templates']
|
||||
exclude_patterns = []
|
||||
|
||||
|
||||
master_doc = 'index'
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
||||
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
html_static_path = ['_static']
|
||||
|
||||
|
||||
|
||||
latex_documents = [
|
||||
(master_doc, 'ptulsconv.tex', u'ptulsconv Documentation',
|
||||
u'Jamie Hardt', 'manual'),
|
||||
]
|
||||
|
||||
|
||||
# -- Options for Epub output -------------------------------------------------
|
||||
|
||||
# Bibliographic Dublin Core info.
|
||||
epub_title = project
|
||||
|
||||
# The unique identifier of the text. This can be a ISBN number
|
||||
# or the project homepage.
|
||||
#
|
||||
# epub_identifier = ''
|
||||
|
||||
# A unique identification for the text.
|
||||
#
|
||||
# epub_uid = ''
|
||||
|
||||
# A list of files that should not be packed into the epub file.
|
||||
epub_exclude_files = ['search.html']
|
||||
|
||||
|
||||
# -- Extension configuration -------------------------------------------------
|
||||
|
||||
# -- Options for todo extension ----------------------------------------------
|
||||
|
||||
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||
todo_include_todos = True
|
||||
21
docs/source/index.rst
Normal file
21
docs/source/index.rst
Normal file
@@ -0,0 +1,21 @@
|
||||
.. ptulsconv documentation master file, created by
|
||||
sphinx-quickstart on Fri Nov 18 10:40:33 2022.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
Welcome to ptulsconv's documentation!
|
||||
=====================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
quickstart
|
||||
tagging
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
91
docs/source/quickstart.rst
Normal file
91
docs/source/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.
|
||||
|
||||
|
||||
86
docs/source/tagging.rst
Normal file
86
docs/source/tagging.rst
Normal file
@@ -0,0 +1,86 @@
|
||||
Tagging
|
||||
=======
|
||||
|
||||
Fields in Clip Names
|
||||
--------------------
|
||||
|
||||
Track names, track comments, and clip names can also contain meta-tags, or
|
||||
"fields," to add additional columns to the CSV 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 CSV output, clips with the field
|
||||
will have it, and clips without will have the column with an empty value.
|
||||
|
||||
For example, if two clips are named:
|
||||
|
||||
`"Squad fifty-one, what is your status?" [FUTZ] {Ch=Dispatcher} [ADR]`
|
||||
|
||||
`"We are ten-eight at Rampart Hospital." {Ch=Gage} [ADR]`
|
||||
|
||||
The output will contain the range:
|
||||
|
||||
|
||||
|
||||
+-----+-----------------------------------------+------------+------+-----+
|
||||
| ... | Clip Name | Ch | FUTZ | ADR |
|
||||
+=====+=========================================+============+======+=====+
|
||||
| ... | "Squad fifty-one, what is your status?" | Dispatcher | FUTZ | ADR |
|
||||
+-----+-----------------------------------------+------------+------+-----+
|
||||
| ... | "We are ten-eight at Rampart Hospital." | Gage | | ADR |
|
||||
+-----+-----------------------------------------+------------+------+-----+
|
||||
|
||||
|
||||
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.
|
||||
|
||||
Using @ to Apply Fields to a Time Range of Clips
|
||||
--------------------------------------------------
|
||||
|
||||
A clip name beginning with "@" will not be included in the CSV 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.
|
||||
|
||||
Using & to Combine Clips
|
||||
--------------------------
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user