jamie/ptulsconv
1
0
Fork 0
mirror of https://github.com/iluvcapra/ptulsconv.git synced 2025-12-31 08:50:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

Restructuring documenation

Browse Source 
Swiching to readthedocs.io
This commit is contained in:
Jamie Hardt
2022-11-18 11:33:47 -08:00
parent 29e1753b18
commit 528bd949ca
9 changed files with 198 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
.readthedocs.yaml Normal file
View File

@@ -0,0 +1,29 @@
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the version of Python and other tools you might need
build:
os: ubuntu-20.04
tools:
python: "3.10"
# You can also specify other tool versions:
# nodejs: "16"
# rust: "1.55"
# golang: "1.17"
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/source/conf.py
#If using Sphinx, optionally build your docs in additional formats such as PDF
formats:
- pdf
#Optionally declare the Python requirements required to build your docs
python:
install:
- requirements: requirements.txt

3
.vscode/settings.json vendored Normal file
View File

@@ -0,0 +1,3 @@
{
"esbonio.sphinx.confDir": ""
}

3
README.md
View File

@@ -1,3 +1,4 @@
[![Documentation Status](https://readthedocs.org/projects/ptulsconv/badge/?version=latest)](https://ptulsconv.readthedocs.io/en/latest/?badge=latest)
![](https://img.shields.io/github/license/iluvcapra/ptulsconv.svg)
![](https://img.shields.io/pypi/pyversions/ptulsconv.svg)
[![](https://img.shields.io/pypi/v/ptulsconv.svg)][pypi]
@@ -12,7 +13,7 @@ Read Pro Tools text exports and generate PDF reports, JSON output.
## Quick Start
For a quick overview of how to cue ADR with `ptulsconv`, check out the [Quickstart](doc/QUICKSTART.md).
For a quick overview of how to cue ADR with `ptulsconv`, check out the [Quickstart](docs/QUICKSTART.rst).
## Installation

20
docs/Makefile Normal file
View File

@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

69
docs/source/conf.py Normal file
View 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
View 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`

43
doc/QUICKSTART.md → docs/source/quickstart.rst
View File

@@ -1,32 +1,40 @@
# Quick Start for ADR Spotting and Reporting with `ptulsconv`
Quick Start
===========
## Step 1: Use Pro Tools to spot ADR Lines
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.
1. Create a new Pro Tools session, name this session after your project.
1. Create new tracks, one for each character. Name each track after a
#. 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.
1. On each track, create a clip group (or edit in some audio) at the time you
#. 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
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,
* 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
* 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.
* 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:
@@ -35,23 +43,19 @@ So for example, some ADR spot's clip name might look like:
These tags can appear in any order.
- You can add the name of an actor to a character's track, so this information
* 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
* 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
* 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.
Many tags are available to express different details of each line, like
priority, time budget, picture version and reel, notes etc. charater or the
project, find them by running `ptulsconv` with the `--show-available-tags`
option.
## Step 3: Export Relevant Tracks from Pro Tools as a Text File
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.
@@ -59,7 +63,8 @@ using the Timecode time format.
Do not export crossfades.
## Step 4: Run `ptulsconv` on the Text Export
Step 4: Run `ptulsconv` on the Text Export
------------------------------------------
In your Terminal, run the following command:

54
doc/HOWTO.md → docs/source/tagging.rst
View File

@@ -1,15 +1,8 @@
# How To Use `ptulsconv`
Tagging
=======
## Theory of Operation
[Avid Pro Tools][avp] exports a tab-delimited text file organized in multiple
parts with an uneven syntax that usually can't "drop in" to other tools like
Excel or Filemaker. `ptulsconv` will accept a text export from Pro Tools and,
by default, create a set of PDF reports useful for ADR reporting.
## Tagging
### Fields in Clip Names
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
@@ -19,9 +12,13 @@ name:
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`.
@@ -39,13 +36,19 @@ For example, if two clips are named:
The output will contain the range:
|...| PT.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
+-----+-----------------------------------------+------------+------+-----+
| ... | 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
@@ -63,7 +66,8 @@ 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 Span of Clips
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.
@@ -71,7 +75,8 @@ 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
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
@@ -79,14 +84,3 @@ 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.
## What is `ptulsconv` Useful For?
The main purpose of `ptulsconv` is to read a Pro Tools text export and convert
it into PDFs useful for ADR recording.
## Is it useful for anything else?

18
man/ptulsconv.1
View File

@@ -1,18 +0,0 @@
.\" Manpage for ptulsconv
.\" Contact https://github.com/iluvcapra/ptulsconv
.TH ptulsconv 1 "15 May 2020" "0.8.2" "ptulsconv man page"
.SH NAME
.BR "ptulsconv" " \- convert
.IR "Avid Pro Tools" " text exports"
.SH SYNOPSIS
ptulsconv [OPTIONS] Export.txt
.SH DESCRIPTION
Convert a Pro Tools text export into ADR reports.
.SH OPTIONS
.IP "-h, --help"
show a help message and exit.
.TP
.RI "--show-available-tags"
Print a list of tags that are interpreted and exit.
.SH AUTHOR
Jamie Hardt (contact at https://github.com/iluvcapra/ptulsconv)