diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..764ad2b --- /dev/null +++ b/.readthedocs.yaml @@ -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 diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..a7d0fc7 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "esbonio.sphinx.confDir": "" +} \ No newline at end of file diff --git a/README.md b/README.md index b7844d5..8bbb55a 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -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) diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..f250a5c --- /dev/null +++ b/docs/source/conf.py @@ -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 diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..9250eba --- /dev/null +++ b/docs/source/index.rst @@ -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` diff --git a/doc/QUICKSTART.md b/docs/source/quickstart.rst similarity index 69% rename from doc/QUICKSTART.md rename to docs/source/quickstart.rst index 0a08a97..9aa6e50 100644 --- a/doc/QUICKSTART.md +++ b/docs/source/quickstart.rst @@ -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: diff --git a/doc/HOWTO.md b/docs/source/tagging.rst similarity index 62% rename from doc/HOWTO.md rename to docs/source/tagging.rst index d2d8395..fff873c 100644 --- a/doc/HOWTO.md +++ b/docs/source/tagging.rst @@ -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,17 +12,21 @@ 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 | ... | + ++-----+---------------------+-------------------+---+----+--------+-----+ +| ... | 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. +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. +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: @@ -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,22 +75,12 @@ 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 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? - - +become the finish time of the row. \ No newline at end of file diff --git a/man/ptulsconv.1 b/man/ptulsconv.1 deleted file mode 100644 index f02858c..0000000 --- a/man/ptulsconv.1 +++ /dev/null @@ -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)