Metadata-Version: 2.1
Name: ptulsconv
Version: 0.8.1
Summary: Parse and convert Pro Tools text exports
Home-page: https://github.com/iluvcapra/ptulsconv
Author: Jamie Hardt
License: MIT
Project-URL: Source, https://github.com/iluvcapra/ptulsconv
Project-URL: Issues, https://github.com/iluvcapra/ptulsconv/issues
Keywords: text-processing parsers film tv editing editorial
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Multimedia
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.8
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Text Processing :: Filters
Description-Content-Type: text/markdown
License-File: LICENSE

![](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]
![](https://img.shields.io/pypi/wheel/ptulsconv.svg)
![Lint and Test](https://github.com/iluvcapra/ptulsconv/actions/workflows/python-package.yml/badge.svg) 

[pypi]: https://pypi.org/project/ptulsconv/


# ptulsconv

Read Pro Tools text exports and generate PDF reports, JSON output.
 

## Theory of Operation

[Avid Pro Tools][avp] can be used to make spotting notes for ADR recording
sessions by creating spotting regions with descriptive text and exporting the
session as text. This file can then be dropped into Excel or any CSV-reading
app like Filemaker Pro.

**ptulsconv** accepts a text export from Pro Tools and automatically creates
PDF and CSV documents for use in ADR spotting, recording, editing and 
reporting, and supplemental JSON documents can be output for use with other
workflows.

### Reports Generated by ptulsconv by Default

1. "ADR Report" lists every line in an export with most useful fields, sorted 
   by time.
2. "Continuity" lists every scene sorted by time.
3. "Line Count" lists a count of every line, collated by reel number and by
   effort/TV/optional line designation.
4. "CSV" is a folder of files of all lines collated by character and reel
   as CSV files, for use by studio cueing workflows.
5. "Director Logs" is a folder of PDFs formatted like the "ADR Report" except
   collated by character.
6. "Supervisor Logs" creates a PDF report for every character, with one line
   per page, optimized for note-taking.
7. "Talent Scripts" is a minimal PDF layout of just timecode and line prompt,
   collated by character.


[avp]: http://www.avid.com/pro-tools


### Adding Detailed Info to Clip Names with Fields

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:

|...| PT.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 character 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 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:

|...| 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

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 prevails.

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

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 (later 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.


## Installation

The easiest way to install on your site is to use `pip`:

    % pip3 install ptulsconv
    
This will install the necessary libraries on your host and gives you 
command-line access to the tool through an entry-point `ptulsconv`. In a 
terminal window type `ptulsconv -h` for a list of available options.

