jamie/ptulsconv
1
0
Fork 0
mirror of https://github.com/iluvcapra/ptulsconv.git synced 2026-01-02 01:40:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update HOWTO.md

Browse Source
This commit is contained in:
Jamie Hardt
2022-11-06 13:25:52 -08:00
parent f6ee807ede
commit 09b3f9349b
1 changed files with 31 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
doc/HOWTO.md
View File

@@ -1,33 +1,12 @@
# How To Use `ptulsconv` # How To Use `ptulsconv`
## 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.
### Theory of Operation ### Theory of Operation
[Avid Pro Tools][avp] exports a tab-delimited text file organized in multiple [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 parts with an uneven syntax that usually can't "drop in" to other tools like
Excel or Filemaker. This project implements a simple Mac OS X application that Excel or Filemaker. `ptulsconv` will accept a text expoet from Pro Tools
accepts a text export from Pro Tools and converts it into a [CSV][csv] of the
clips, unfolding track and session data in the process, and also parsing
additional columns from the clip, track, and session name.
Importing a normal text export outputs a CSV with one row for each clip, like ## Tagging
this:
| PT.Session.Name | PT.Track.Name | PT.Clip.Number | PT.Clip.Name | PT.Clip.Start | PT.Clip.Finish | PT.Clip.Muted | ... |
|-----------------|---------------|----------------|--------------|-----------------|-----------------|---------------|-----|
| Test Session | Track 1 | 1 | Audio 1-01 |01:00:00:05 |01:01:00:12 | Unmuted |...|
| Test Session | Track 1 | 2 | Audio 1-02 |01:01:00:12 |01:01:00:20 | Unmuted |...|
etc... Each clip has a column for the track name of the clip in addition to the
session name. A column for the track comments is also included. The first row
of the output *always* contains column headings.
[avp]: http://www.avid.com/pro-tools
[csv]: https://tools.ietf.org/html/rfc4180
### Fields in Clip Names ### Fields in Clip Names
@@ -39,7 +18,7 @@ name:
The row output for this clip will contain columns for the values: The row output for this clip will contain columns for the values:
|...| PT.Clip.Name| note | V | FX | DESIGN | ...| |...| Clip Name| note | V | FX | DESIGN | ...|
|---|------------|------|---|----|--------|----| |---|------------|------|---|----|--------|----|
|...| Fireworks explosion| Replace for final | 1 | FX | DESIGN | ... | |...| Fireworks explosion| Replace for final | 1 | FX | DESIGN | ... |
@@ -67,32 +46,44 @@ The output will contain the range:
### Fields in Track Names and Markers ### 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 Fields set in track names, and in track comments, will be applied to *each*
contains the text `{Dept=Foley}` for example, every clip on that track will have a "Foley" value in a "Dept" column. 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. 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 Fields set in markers, and in marker comments, will be applied to all clips
in markers are applied cumulatively from breakfast to dinner in the session. The latest marker applying to a clip has whose finish is *after* that marker. Fields in markers are applied cumulatively
precedence, so if one marker comes after the other, but both define a field, the value in the later marker 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 An important note here is that, always, fields set on the clip name have the
name, the same field set on the track, the value set on the clip will prevail. 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 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 A clip name beginning with "@" will not be included in the CSV output, but its
its time range on lower tracks. 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 If track 1 has a clip named `@ {Sc=1- The House}`, any clips beginning within
field `Sc` with that value. that range on lower tracks will have a field `Sc` with that value.
### Using `[AP]` to Combine Clips ### Using `&` to Combine Clips
A clip name setting the `[AP]` field will have its parsed clip name appended to the following cue, and the fields of A clip name beginning with `&` will have its parsed clip name appended to the
following cues will be applied (earlier clips having precedence). The clips need not be touching, and the clips will preceding cue, and the fields of following cues will be applied, earlier clips
be combined into a single row of the output. The start time of the first clip will become the start time of the row, having precedence. The clips need not be touching, and the clips will be
and the finish time of the last clip will become the finish time of the row. 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? ## Is it useful for anything else?