tictacsync 0.91a0__py3-none-any.whl → 0.96a0__py3-none-any.whl

tictacsync/timeline.py

@@ -303,7 +303,7 @@ class AudioStitcherVideoMerger:
     Typically each found video is associated with an AudioStitcherVideoMerger
     instance. AudioStitcherVideoMerger does the actual audio-video file
     processing of merging AudioStitcherVideoMerger.videoclip (gen. a video)
-    with all audio files in  AudioStitcherVideoMerger.edited_audio as
+    with all audio files in  AudioStitcherVideoMerger.soxed_audio as
     determined by the Matcher object (Matcher instanciates and manages
     AudioStitcherVideoMerger objects).
 
@@ -317,46 +317,58 @@ class AudioStitcherVideoMerger:
     project.
 
 
+    Class attribute
+
+        tempoed_recs : dict as {Recording : path}
+
+            a cache for already time-stretched audio files. Keys are elements
+            of matched_audio_recordings and the value are tuples:
+            (factor, file_handle), the file_handle points to the precedently
+            produced NamedTemporaryFile; factor is the value that was used in
+            the sox tempo transform.
+
     Attributes:
 
         videoclip : a Recording instance
             The video to which audio files are synced
 
-        edited_audio : dict as {Recording : path}
-            keys are elements of matched_audio_recordings of class Recording
-            and the value stores the Pathlib path of the eventual edited
-            audio (trimmed , padded or time stretched). Before building the
-            audio_montage, path points to the initial
-            Recording.valid_sound
+        ref_audio : a Recording instance
+            If no video is present, this is the reference audio to which others
+            audio files are synced
+
+        soxed_audio : dict as {Recording : path}
+            keys are elements of matched_audio_recordings and the value are
+            the Pathlib path of the eventual edited audio(trimmed or padded).
 
         synced_clip_dir : Path
             where synced clips are written
 
     """
+    tempoed_recs = {}
 
     def __init__(self, video_clip):
         self.videoclip = video_clip
         # self.matched_audio_recordings = []
-        self.edited_audio = {}
+        self.soxed_audio = {}
         logger.debug('instantiating AudioStitcherVideoMerger for %s'%
                             video_clip)
 
     def add_matched_audio(self, audio_rec):
         """
-        Populates AudioStitcherVideoMerger.edited_audio,
+        Populates AudioStitcherVideoMerger.soxed_audio,
         a dict as {Recording : path}
 
         This fct is called
         within Matcher.scan_audio_for_each_videoclip()
 
-        Returns nothing, fills self.edited_audio dict with
+        Returns nothing, fills self.soxed_audio dict with
         matched audio.
 
         """
-        self.edited_audio[audio_rec] = audio_rec.AVpath
+        self.soxed_audio[audio_rec] = audio_rec.AVpath
         """
-        Here at this point, self.edited_audio[audio_rec] is unedited but
-        after a call to _edit_audio_file(), edited_audio[audio_rec] points to
+        Here at this point, self.soxed_audio[audio_rec] is unedited but
+        after a call to _edit_audio_file(), soxed_audio[audio_rec] points to
         a new file and audio_rec.AVpath is unchanged.
         """
         return
@@ -364,9 +376,9 @@ class AudioStitcherVideoMerger:
     def get_matched_audio_recs(self):
         """
         Returns audio recordings that overlap self.videoclip.
-        Simply keys of self.edited_audio dict
+        Simply keys of self.soxed_audio dict
         """
-        return list(self.edited_audio.keys())
+        return list(self.soxed_audio.keys())
 
     def _get_audio_devices(self):
         devices = set([r.device for r in self.get_matched_audio_recs()])
@@ -375,6 +387,13 @@ class AudioStitcherVideoMerger:
         logger.debug('devices %s'%devices)
         return devices
 
+    def _get_secondary_audio_devices(self):
+        devices = set([r.device for r in self.get_matched_audio_recs()])
+        logger.debug('get_matched_audio_recs: %s'%
+            pprint.pformat(self.get_matched_audio_recs()))
+        logger.debug('devices %s'%devices)
+        return devices
+
     def _get_all_recordings_for(self, device):
         # return recordings for a particular device, sorted by time
         recs = [a for a in self.get_matched_audio_recs() if a.device == device]
@@ -382,58 +401,77 @@ class AudioStitcherVideoMerger:
         return recs
 
     def _dedrift_rec(self, rec):
-        initial_duration = sox.file_info.duration(
-            _pathname(rec.AVpath))
-        sox_transform = sox.Transformer()
-        # tempo_scale_factor = rec.device_relative_speed
+        # instanciates a sox.Transformer() with tempo() effect
+        # add applies it via a call to _edit_audio_file(rec, sox_transform)
         tempo_scale_factor = rec.device_relative_speed
         audio_dev = rec.device.name
         video_dev = self.videoclip.device.name
+        print('when merging with [gold1]%s[/gold1].'%self.videoclip)
         if tempo_scale_factor > 1:
-            print('[gold1]%s[/gold1] clock too fast relative to [gold1]%s[/gold1] so file is too long by a %f factor;\n'%
+            print('Because [gold1]%s[/gold1] clock too fast relative to [gold1]%s[/gold1]: file is too long by a %.12f factor;'%
                 (audio_dev, video_dev, tempo_scale_factor))
         else:
-            print('hence [gold1]%s[/gold1] clock too slow relative to [gold1]%s[/gold1] so file is short by a %f factor\n'%
+            print('Because [gold1]%s[/gold1] clock too slow relative to [gold1]%s[/gold1]: file is short by a %.12f factor'%
                 (audio_dev, video_dev, tempo_scale_factor))
-        sox_transform.tempo(tempo_scale_factor)
-        # scaled_file = self._get_soxed_file(rec, sox_transform)
-        logger.debug('sox_transform %s'%sox_transform.effects)
-        self._edit_audio_file(rec, sox_transform)
-        scaled_file_name = _pathname(self.edited_audio[rec])
-        new_duration = sox.file_info.duration(scaled_file_name)
-        # goal_duration = rec.get_corrected_duration()
-        logger.debug('initial_duration %f new_duration %f ratio:%f'%(
-            initial_duration, new_duration, initial_duration/new_duration))
+        logger.debug('tempoed_recs dict:%s'%AudioStitcherVideoMerger.tempoed_recs)
+        if rec in AudioStitcherVideoMerger.tempoed_recs:
+            logger.debug('%s already tempoed'%rec)
+            cached_factor, cached_file = AudioStitcherVideoMerger.tempoed_recs[rec]
+            error_factor = tempo_scale_factor/cached_factor
+            logger.debug('tempo factors, needed: %f cached %f'%(tempo_scale_factor,cached_factor))
+            delta_cache = abs((1 - error_factor)*rec.get_original_duration())
+            logger.debug('error if cache is used: %f ms'%(delta_cache*1e3))
+            delta_cache_is_ok = delta_cache < yaltc.MAXDRIFT
+        else:
+            delta_cache_is_ok = False
+        if delta_cache_is_ok:
+            logger.debug('ok, will use %s'%cached_file)
+            self.soxed_audio[rec] = cached_file
+        else:
+            logger.debug('%s not tempoed yet'%rec)            
+            sox_transform = sox.Transformer()
+            sox_transform.tempo(tempo_scale_factor)
+            # scaled_file = self._get_soxed_file(rec, sox_transform)
+            logger.debug('sox_transform %s'%sox_transform.effects)
+            soxed_fh = self._edit_audio_file(rec, sox_transform)
+            scaled_file_name = _pathname(soxed_fh)
+            AudioStitcherVideoMerger.tempoed_recs[rec] = (tempo_scale_factor, soxed_fh)
+            new_duration = sox.file_info.duration(scaled_file_name)
+            initial_duration = sox.file_info.duration(
+                _pathname(rec.AVpath))
+            logger.debug('Verif: initial_duration %.12f new_duration %.12f ratio:%.12f'%(
+                initial_duration, new_duration, initial_duration/new_duration))
+            logger.debug('delta duration %f ms'%((new_duration-initial_duration)*1e3))
 
     def _get_concatenated_audiofile_for(self, device):
         """
         return a handle for the final audio file formed by all detected
-        overlapping recordings, produced by the same specified device.
+        overlapping recordings, produced by the same audio recorder.
         
         """
         logger.debug('concatenating device %s'%str(device))
-        recordings = self._get_all_recordings_for(device)
+        audio_recs = self._get_all_recordings_for(device)
         # [TODO here] Check if all unidentified device files are not
         # overlapping because they are considered produced by the same
         # device. If some overlap then necessarily they're from different
         # ones. List the files and warn the user there is a risk of error if
         # they're not from the same device.
 
-        logger.debug('%i audio files for videoclip %s:'%(len(recordings),
+        logger.debug('%i audio files for videoclip %s:'%(len(audio_recs),
             self.videoclip))
-        for r in recordings:
+        for r in audio_recs:
             logger.debug('  %s'%r)
+        # ratio between real samplerates of audio and videoclip
         speeds = numpy.array([rec.get_speed_ratio(self.videoclip)
-                                    for rec in recordings])
+                                    for rec in audio_recs])
         mean_speed = numpy.mean(speeds)
-        for r in recordings:
-            r.device_relative_speed = mean_speed
-            # r.device_relative_speed = 0.9
-            logger.debug('set device_relative_speed for %s'%r)
-            logger.debug(' value: %f'%r.device_relative_speed)
-            r.set_time_position_to(self.videoclip)
-            logger.debug('time_position for %s: %fs relative to %s'%(r,
-                r.time_position, self.videoclip))
+        for audio in audio_recs:
+            audio.device_relative_speed = mean_speed
+            logger.debug('set device_relative_speed for %s'%audio)
+            logger.debug(' value: %f'%audio.device_relative_speed)
+            audio.set_time_position_to(self.videoclip)
+            logger.debug('time_position for %s: %fs relative to %s'%(audio,
+                audio.time_position, self.videoclip))
         # st_dev_speeds just to check for anomalous situation
         st_dev_speeds = numpy.std(speeds)
         logger.debug('mean speed for %s: %.6f std dev: %.0e'%(device,
@@ -458,7 +496,7 @@ class AudioStitcherVideoMerger:
 
         # process first element 'by hand' outside the loop
         # first_audio is a Recording, not a path nor filehandle
-        first_audio = recordings[0]
+        first_audio = audio_recs[0]
         needs_dedrift, delta = first_audio.needs_dedrifting()
         logger.debug('first audio is %s'%first_audio)
         logger.debug('checking drift, first audio: delta of %0.2f ms'%(
@@ -470,8 +508,8 @@ class AudioStitcherVideoMerger:
         self._pad_or_trim_first_audio(first_audio)
         # loop for the other files
         # growing_file = first_audio.edited_version
-        growing_file = self.edited_audio[first_audio]
-        for i, rec in enumerate(recordings[1:]):
+        growing_file = self.soxed_audio[first_audio]
+        for i, rec in enumerate(audio_recs[1:]):
             logger.debug('Padding and joining for %s'%rec)
             needs_dedrift, delta = rec.needs_dedrifting()
             logger.debug('next audio is %s'%rec)
@@ -494,7 +532,7 @@ class AudioStitcherVideoMerger:
                     (rec,rec.time_position,end_time))
             self._pad_file(rec, pad_duration)
             # new_file = rec.edited_version
-            new_file = self.edited_audio[rec]
+            new_file = self.soxed_audio[rec]
             growing_file = self._concatenate_audio_files(growing_file, new_file)
         end_time = sox.file_info.duration(growing_file.name)
         logger.debug('total edited audio duration  %.2f s'%end_time)
@@ -507,7 +545,7 @@ class AudioStitcherVideoMerger:
         TODO: check if first_rec is a Recording or tempfile (maybe a tempfile if dedrifted)
         NO: will change tempo after trimming/padding
 
-        Store (into Recording.edited_audio dict) the handle  of the sox processed
+        Store (into Recording.soxed_audio dict) the handle  of the sox processed
         first recording, padded or chopped according to AudioStitcherVideoMerger.videoclip
         starting time. Length of the written file can differ from length of the
         submitted Recording object if drift is corrected with sox tempo
@@ -571,22 +609,25 @@ class AudioStitcherVideoMerger:
     def _edit_audio_file(self, audio_rec, sox_transform):
         """
         Apply the specified sox_transform onto the audio_rec and update
-        self.edited_audio dict with the result (with audio_rec as the key)
+        self.soxed_audio dict with the result (with audio_rec as the key)
+        Returns the filehandle of the result.
         """
         output_fh = tempfile.NamedTemporaryFile(suffix='.wav', delete=DEL_TEMP)
         logger.debug('transform: %s'%sox_transform.effects)
-        recording_fh = self.edited_audio[audio_rec]
+        recording_fh = self.soxed_audio[audio_rec]
         logger.debug('for recording %s, matching %s'%(audio_rec,
                                                 self.videoclip))
         input_file = _pathname(recording_fh)
-        logger.debug('AudioStitcherVideoMerger.edited_audio[audio_rec]: %s'%
+        logger.debug('AudioStitcherVideoMerger.soxed_audio[audio_rec]: %s'%
                                                     input_file)
         out_file = _pathname(output_fh)
         logger.debug('sox in and out files: %s %s'%(input_file, out_file))
+        logger.debug('calling sox_transform.build()')
         status = sox_transform.build(input_file, out_file, return_output=True )
         logger.debug('sox.build exit code %s'%str(status))
         # audio_rec.edited_version = output_fh
-        self.edited_audio[audio_rec] = output_fh
+        self.soxed_audio[audio_rec] = output_fh
+        return output_fh
 
     def _write_ISOs(self, edited_audio_all_devices):
         """
@@ -605,11 +646,11 @@ class AudioStitcherVideoMerger:
                 leftCAM/
 
                     canon24fps01.MOV ━━━━┓ name of clip is name of folder
-                    canon24fps01.ISO/ <━━┛
+                    canon24fps01_ISO/ <━━┛
                         chan_1.wav     
                         chan_2.wav     
                     canon24fps02.MOV 
-                    canon24fps01.ISO/ 
+                    canon24fps01_ISO/ 
                         chan_1.wav
                         chan_2.wav
 
@@ -650,7 +691,7 @@ class AudioStitcherVideoMerger:
         video_stem_WO_suffix = synced_clip_file.stem
         # video_stem_WO_suffix = synced_clip_file.stem.split('.')[0]
         # OUT_DIR_DEFAULT, D2 = ISOsDIR.split('/')
-        ISOdir = synced_clip_dir/(video_stem_WO_suffix + '.ISO')
+        ISOdir = synced_clip_dir/(video_stem_WO_suffix + '_ISO')
         os.makedirs(ISOdir, exist_ok=True)
         logger.debug('edited_audio_all_devices %s'%edited_audio_all_devices)
         logger.debug('ISOdir %s'%ISOdir)
@@ -683,16 +724,16 @@ class AudioStitcherVideoMerger:
         In details:
 
         If no device tracks.txt file declared a mix track (or if tracks.txt is
-        absent), a mix is done programmatically. Two possibilities:
+        absent) a mix is done programmatically. Two possibilities:
 
             #1- no stereo pairs were declared: a global mono mix is returned.
             #2- one or more stereo pair mics were used and declared (micL, micR):
             a global stereo mix is returned with mono tracks panned 50-50
 
-        If device has an associated Tracks description AND it declares a(mono or
+        If device has an associated Tracks description AND it declares a (mono or
         stereo) mix track, this fct returns a tempfile containing the
-        corresponding tracks, simpley extarcting them from multichan_tmpfl
-        (thos covers cases #3 and #4)
+        corresponding tracks, simply extracting them from multichan_tmpfl
+        (those covers cases #3 and #4)
 
         Args:
             device : device_scanner.Device dataclass
@@ -763,12 +804,13 @@ class AudioStitcherVideoMerger:
             logger.debug('%s has mix %s'%(device.name, device.tracks.mix))
             logger.debug('device %s'%device)
             # just checking coherency
-            if 'ttc' in device.tracks.rawtrx:
-                trx_TTC_chan = device.tracks.rawtrx.index('ttc')
-            elif 'tc' in device.tracks.rawtrx:
+            if 'tc' in device.tracks.rawtrx:
                 trx_TTC_chan = device.tracks.rawtrx.index('tc')
+            elif 'TC' in device.tracks.rawtrx:
+                trx_TTC_chan = device.tracks.rawtrx.index('TC')
             else:
                 print('Error: no tc or ttc tag in track.txt')
+                print(device.tracks.rawtrx)
                 sys.exit(1)
             logger.debug('TTC chan %i, dev ttc %i'%(trx_TTC_chan, device.ttc))
             if trx_TTC_chan != device.ttc:
@@ -797,17 +839,132 @@ class AudioStitcherVideoMerger:
         logger.debug('stereo_mic_idx_flat %s'%stereo_mic_idx_flat)
         mono_tracks = [i for i in range(1, device.n_chan + 1)
                                 if i not in stereo_mic_idx_flat]
-        logger.debug('mono_tracks: %s'%mono_tracks)
+        logger.debug('mono_tracks (with ttc+zeroed included): %s'%mono_tracks)
         # remove TTC track number
-        mono_tracks.remove(device.ttc + 1)
-        logger.debug('mono_tracks %s'%mono_tracks)
+        to_remove = device.tracks.unused + [device.ttc+1]# unused is sox idx
+        [mono_tracks.remove(t) for t in to_remove]
+        # mono_tracks.remove(device.ttc + 1)
+        logger.debug('mono_tracks (ttc+zeroed removed)%s'%mono_tracks)
         mono_files = [_sox_keep(multichan_tmpfl, [chan]) for chan
                                                     in mono_tracks]
         new_stereo_files = [_sox_mono2stereo(f) for f in mono_files]
         stereo_files = mic_stereo_files + new_stereo_files
         return _sox_mix_files(stereo_files)
 
-    def build_audio_and_write_video(self, top_dir, output_dir,
+    def build_audio_and_write_merged_media(self, top_dir, output_dir,
+                                    write_multicam_structure,
+                                    asked_ISOs, audio_REC_only):
+        # simply bifurcates depending if ref media is video (prob 99%)
+        # (then audio_REC_only == False)
+        # or if ref media is audio (no camera detected)
+        # (with audio_REC_only == True)
+        if not audio_REC_only:
+            self._build_audio_and_write_video(top_dir, output_dir,
+                                    write_multicam_structure, asked_ISOs)
+        else:
+            self._build_and_write_audio(top_dir, output_dir)
+
+    def _build_and_write_audio(self, top_dir, output_dir):
+        """
+        This is called when only audio recorders were found (no cam).
+
+        top_dir: Path, directory where media were looked for
+
+        output_dir: str for optional folder specified as CLI argument, if
+        value is None, fall back to OUT_DIR_DEFAULT
+
+        For each audio devices found overlapping self.ref_audio: pad, trim
+        or stretch audio files by calling _get_concatenated_audiofile_for(), and
+        put them in merged_audio_files_by_device. More than one audio recorder
+        can be used for a shot: that's why merged_audio_files_by_device is a
+        list.
+
+        Returns nothing
+
+        Sets AudioStitcherVideoMerger.final_synced_file on completion to list
+        containing all the synced and patched audio files.
+        """
+        self.ref_audio = self.videoclip # ref audio was stored in videoclip
+        logger.debug('Will merge audio against %s from %s'%(self.ref_audio,
+                                                self.ref_audio.device.name))
+        # eg, suppose the user called tictacsync with 'mondayPM' as top folder
+        # to scan for dailies (and 'somefolder' for output):
+        if output_dir == None:
+            synced_clip_dir = Path(top_dir)/OUT_DIR_DEFAULT # = mondayPM/SyncedMedia
+        else:
+            synced_clip_dir = Path(output_dir)/Path(top_dir).name # = somefolder/mondayPM
+        self.synced_clip_dir = synced_clip_dir
+        os.makedirs(synced_clip_dir, exist_ok=True)
+        logger.debug('synced_clip_dir is: %s'%synced_clip_dir)
+        synced_clip_file = synced_clip_dir/\
+            Path(self.videoclip.new_rec_name).name
+        logger.debug('editing files for %s'%synced_clip_file)
+        self.ref_audio.final_synced_file = synced_clip_file # relative path
+        # Collecting edited audio by device, in (Device, tempfile) pairs:
+        # for a given self.ref_audio, each other audio device will have a sequence
+        # of matched, synced and joined audio files present in a single
+        # edited audio file, returned by _get_concatenated_audiofile_for
+        merged_audio_files_by_device = [
+                            (d, self._get_concatenated_audiofile_for(d)) 
+                            for d in self._get_secondary_audio_devices()]
+        # at this point, audio editing has been done in tempfiles
+        logger.debug('%i elements in merged_audio_files_by_device'%len(
+                                            merged_audio_files_by_device))
+        for d, f, in merged_audio_files_by_device:
+            logger.debug('device: %s'%d.name)
+            logger.debug('file %s of %i channels'%(f.name,
+                                        sox.file_info.channels(f.name)))
+        logger.debug('')
+        if not merged_audio_files_by_device:
+            # no audio file overlaps for this clip
+            return #############################################################
+        logger.debug('will output ISO files since no cam')
+        devices_and_monofiles = [(device, _split_channels(multi_chan_audio))
+                for device, multi_chan_audio
+                in merged_audio_files_by_device]
+        # add device and file from self.ref_audio
+        new_tuple = (self.ref_audio.device,
+                        _split_channels(self.ref_audio.AVpath))
+        devices_and_monofiles.append(new_tuple)
+        logger.debug('devices_and_monofiles: %s'%
+            pprint.pformat(devices_and_monofiles))
+        def _trnm(dev, idx): # used in the loop just below
+            # generates track name for later if asked_ISOs
+            # idx is from 0 to nchan-1 for this device
+            if dev.tracks == None:
+                chan_name = 'chan%s'%str(idx+1).zfill(2)
+            else:
+                # sanitize
+                symbols = set(r"""`~!@#$%^&*()_-+={[}}|\:;"'<,>.?/""")
+                chan_name = dev.tracks.rawtrx[idx]
+                logger.debug('raw chan_name %s'%chan_name)
+                chan_name = chan_name.split(';')[0] # if ex: "lav bob;25"
+                logger.debug('chan_name WO ; lag: %s'%chan_name)
+                chan_name =''.join([e if e not in symbols else ''
+                                    for e in chan_name])
+                logger.debug('chan_name WO special chars: %s'%chan_name)
+                chan_name = chan_name.replace(' ', '_')
+                logger.debug('chan_name WO spaces: %s'%chan_name)
+                chan_name += '_' + dev.name # TODO: make this an option?
+            logger.debug('track_name %s'%chan_name)
+            return chan_name #####################################################
+        # replace device, idx pair with track name (+ device name if many)
+        # loop over devices than loop over tracks
+        names_audio_tempfiles = []
+        for dev, mono_tmpfiles_list in devices_and_monofiles:
+            for idx, monotf in enumerate(mono_tmpfiles_list):
+                track_name = _trnm(dev, idx)
+                logger.debug('track_name %s'%track_name)
+                if track_name[0] == '0': # muted, skip
+                    continue
+                names_audio_tempfiles.append((track_name, monotf))
+        logger.debug('names_audio_tempfiles %s'%names_audio_tempfiles)
+        self._write_ISOs(names_audio_tempfiles)
+        logger.debug('merged_audio_files_by_device %s'%
+                            merged_audio_files_by_device)
+
+
+    def _build_audio_and_write_video(self, top_dir, output_dir,
                                     write_multicam_structure,
                                     asked_ISOs):
         """
@@ -830,12 +987,12 @@ class AudioStitcherVideoMerger:
 
         Sets AudioStitcherVideoMerger.final_synced_file on completion
         """
-        logger.debug(' fct args: top_dir: %s; output_dir: %s; write_multicam_structure: %s; asked_ISOs: %s;'%
+        logger.debug(' fct args: top_dir: %s; output_dir: %s; write_multicam_structure: %s; asked_ISOs: %s'%
             (top_dir, output_dir, write_multicam_structure, asked_ISOs))
         logger.debug('device for rec %s: %s'%(self.videoclip,
             self.videoclip.device))
-        # suppose the user called tictacsync with 'mondayPM' as top folder to
-        # scan for dailies (and 'somefolder' for output):
+        # eg, suppose the user called tictacsync with 'mondayPM' as top folder
+        # to scan for dailies (and 'somefolder' for output):
         if output_dir == None:
             synced_clip_dir = Path(top_dir)/OUT_DIR_DEFAULT # = mondayPM/SyncedMedia
         else:
@@ -850,13 +1007,18 @@ class AudioStitcherVideoMerger:
             Path(self.videoclip.new_rec_name).name
         logger.debug('editing files for %s'%synced_clip_file)
         self.videoclip.final_synced_file = synced_clip_file # relative path
-        # Collecting edited audio by device, in (Device, tempfile) pairs:
+        # Collecting edited audio by device, in (Device, tempfiles) pairs:
         # for a given self.videoclip, each audio device will have a sequence
         # of matched, synced and joined audio files present in a single
         # edited audio file, returned by _get_concatenated_audiofile_for
         merged_audio_files_by_device = [
                             (d, self._get_concatenated_audiofile_for(d)) 
                             for d in self._get_audio_devices()]
+        # at this point, audio editing has been done in multichan wav tempfiles 
+        logger.debug('merged_audio_files_by_device %s'%merged_audio_files_by_device)
+        for d, f, in merged_audio_files_by_device:
+            logger.debug('%s'%d)
+            logger.debug('file %s'%f.name)
         if len(merged_audio_files_by_device) == 0:
             # no audio file overlaps for this clip
             return #############################################################
@@ -926,21 +1088,30 @@ class AudioStitcherVideoMerger:
                 # generates track name for later if asked_ISOs
                 # idx is from 0 to nchan-1 for this device
                 if dev.tracks == None:
-                    tag = 'chan%s'%str(idx+1).zfill(2)
+                    chan_name = 'chan%s'%str(idx+1).zfill(2)
                 else:
-                    # audio_tags = [tag for tag in dev.tracks.rawtrx
-                    #     if tag not in ['ttc','0','tc']]
-                    tag = dev.tracks.rawtrx[idx]
+                    # sanitize
+                    symbols = set(r"""`~!@#$%^&*()_-+={[}}|\:;"'<,>.?/""")
+                    chan_name = dev.tracks.rawtrx[idx]
+                    logger.debug('raw chan_name %s'%chan_name)
+                    chan_name = chan_name.split(';')[0] # if ex: "lav bob;25"
+                    logger.debug('chan_name WO ; lag: %s'%chan_name)
+                    chan_name =''.join([e if e not in symbols else ''
+                                        for e in chan_name])
+                    logger.debug('chan_name WO special chars: %s'%chan_name)
+                    chan_name = chan_name.replace(' ', '_')
+                    logger.debug('chan_name WO spaces: %s'%chan_name)
                 if multiple_recorders:
-                    tag += '_' + dev.name
-                logger.debug('tag %s'%tag)
-                return tag #####################################################
+                    chan_name += '_' + dev.name # TODO: make this an option?
+                logger.debug('track_name %s'%chan_name)
+                return chan_name #####################################################
             # replace device, idx pair with track name (+ device name if many)
             # loop over devices than loop over tracks
             names_audio_tempfiles = []
             for dev, mono_tmpfiles_list in devices_and_monofiles:
                 for idx, monotf in enumerate(mono_tmpfiles_list):
                     track_name = _trnm(dev, idx)
+                    logger.debug('track_name %s'%track_name)
                     if track_name[0] == '0': # muted, skip
                         continue
                     names_audio_tempfiles.append((track_name, monotf))
@@ -977,7 +1148,8 @@ class AudioStitcherVideoMerger:
     def _merge_audio_and_video(self):
         """      
         Calls ffmpeg to join video in self.videoclip.AVpath to
-        audio in self.videoclip.synced_audio
+        audio in self.videoclip.synced_audio. Audio in original video
+        is dropped.
 
         On entry, videoclip.final_synced_file is a Path to an non existing
         file (contrarily to videoclip.synced_audio).
@@ -988,7 +1160,7 @@ class AudioStitcherVideoMerger:
         """
         synced_clip_file = self.videoclip.final_synced_file
         video_path = self.videoclip.AVpath
-        timecode = self.videoclip.get_timecode()
+        timecode = self.videoclip.get_start_timecode_string()
         # self.videoclip.synced_audio = audio_path
         audio_path = self.videoclip.synced_audio
         vid_only_handle = self._keep_VIDEO_only(video_path)
@@ -1004,7 +1176,8 @@ class AudioStitcherVideoMerger:
         ffmpeg_args = (
             ffmpeg
             .input(v_n)
-            .output(out_n, shortest=None, vcodec='copy',
+            # .output(out_n, shortest=None, vcodec='copy',
+            .output(out_n, vcodec='copy',
                 timecode=timecode)
             .global_args('-i', a_n, "-hide_banner")
             .overwrite_output()
@@ -1015,7 +1188,8 @@ class AudioStitcherVideoMerger:
             _, out = (
             ffmpeg
             .input(v_n)
-            .output(out_n, shortest=None, vcodec='copy',
+            .output(out_n, vcodec='copy',
+            # .output(out_n, shortest=None, vcodec='copy',
                 # metadata='reel_name=foo', not all container support gen MD
                 timecode=timecode,
                 )
@@ -1053,7 +1227,7 @@ class Matcher:
         recordings : list of Recording instances
             all the scanned recordings with valid TicTacCode, set in __init__()
 
-        video_mergers : list
+        mergers : list
             of AudioStitcherVideoMerger Class instances, built by
             scan_audio_for_each_videoclip(); each video has a corresponding
             AudioStitcherVideoMerger object. An audio_stitch doesn't extend
@@ -1070,7 +1244,7 @@ class Matcher:
         
         """
         self.recordings = recordings_list
-        self.video_mergers = []
+        self.mergers = []
 
     def _rename_all_recs(self):
         """
@@ -1118,12 +1292,12 @@ class Matcher:
                     logger.debug('recording %s overlaps,'%(audio))
                     # print('  recording [gold1]%s[/gold1] overlaps,'%(audio))
             if len(audio_stitch.get_matched_audio_recs()) > 0:
-                self.video_mergers.append(audio_stitch)
+                self.mergers.append(audio_stitch)
             else:
                 logger.debug('\n  nothing\n')
                 print('No overlap found for %s'%videoclip.AVpath.name)
                 del audio_stitch
-        logger.debug('%i video_mergers created'%len(self.video_mergers))
+        logger.debug('%i mergers created'%len(self.mergers))
 
     def _does_overlap(self, videoclip, audio_rec):
         A1, A2 = audio_rec.get_start_time(), audio_rec.get_end_time()
@@ -1136,25 +1310,33 @@ class Matcher:
         case4 = R1 < A2 < R2
         return case1 or case2 or case3 or case4
 
-    def shrink_gaps_between_takes(self, with_gap=CLUSTER_GAP):
+    def shrink_gaps_between_takes(self, CLI_offset, with_gap=CLUSTER_GAP):
         """
         for single cam shootings this simply sets the gap between takes,
         tweaking each vid timecode metadata to distribute them next to each
-        other along NLE timeline. For multicam takes, shifts are computed so
+        other along NLE timeline.
+
+Moves clusters at the timelineoffset
+
+        For multicam takes, shifts are computed so
         video clusters are near but dont overlap, ex: 
 
-        Cluster 1           Cluster 2
-        1111111111111        2222222222 (cam A)
-           11111111111[...]222222222 (cam B)
+        Cluster 1                    Cluster 2
+        1111111111111                 2222222222 (cam A)
+           11111111111[inserted gap]222222222 (cam B)
 
         or
-        1111111111111    222222 (cam A)
-          1111111     22222 (cam B)
+        1111111111111[inserted   222222 (cam A)
+          1111111     gap]222222222 (cam B)
+
+        argument:
+            CLI_offset (str), option from command-line
+            with_gap (float), the gap duration in seconds
 
         Returns nothing, changes are done in the video files metadata
         (each referenced by Recording.final_synced_file)
         """
-        vids = [m.videoclip for m in self.video_mergers]
+        vids = [m.videoclip for m in self.mergers]
         logger.debug('vids %s'%vids)
         if len(vids) == 1:
             logger.debug('just one take, no gap to shrink')
@@ -1210,17 +1392,25 @@ class Matcher:
         cummulative_offsets = [td.total_seconds() for td in cummulative_offsets]
         logger.debug('cummulative_offsets: %s'%cummulative_offsets)
         time_of_first = clusters[0]['start']
+        # compute CLI_offset_in_seconds from HH:MM:SS:FF in CLI_offset
+        h, m, s, f = [float(s) for s in CLI_offset[0].split(':')]
+        logger.debug('CLI_offset float values %s'%[h,m,s,f])
+        CLI_offset_in_seconds = 3600*h + 60*m + s + f/vids[0].get_framerate()
+        logger.debug('CLI_offset in seconds %f'%CLI_offset_in_seconds)
         offset_for_all_clips = - from_midnight(time_of_first).total_seconds()
+        offset_for_all_clips += CLI_offset_in_seconds
         logger.debug('time_of_first: %s'%time_of_first)
         logger.debug('offset_for_all_clips: %s'%offset_for_all_clips)
         for cluster, offset in zip(clusters, cummulative_offsets):
+            # first one starts at 00:00:00:00
             total_offset = offset + offset_for_all_clips
             logger.debug('for %s offset in sec: %f'%(cluster['vids'],
                     total_offset))
             for vid in cluster['vids']:
-                tc = vid.get_timecode(with_offset=total_offset)
+                # tc = vid.get_start_timecode_string(CLI_offset, with_offset=total_offset)
+                tc = vid.get_start_timecode_string(with_offset=total_offset)
                 logger.debug('for %s old tc: %s new tc %s'%(vid,
-                    vid.get_timecode(), tc))
+                    vid.get_start_timecode_string(), tc))
                 vid.write_file_timecode(tc)
         return