tictacsync 0.3a4__py3-none-any.whl → 0.5a0__py3-none-any.whl

tictacsync/timeline.py

@@ -9,14 +9,16 @@ from rich import print
 from itertools import groupby
 # import opentimelineio as otio
 from datetime import timedelta
-import pprint, shutil, os
+import pprint, shutil, os, sys
 from subprocess import Popen, PIPE
 
 from inspect import currentframe, getframeinfo
 try:
     from . import yaltc
+    from . import device_scanner
 except:
     import yaltc
+    import device_scanner
 
 CLUSTER_GAP = 0.5 # secs between multicam clusters
 DEL_TEMP = False
@@ -26,13 +28,13 @@ OUT_DIR_DEFAULT = 'SyncedMedia'
 # utility for accessing pathnames
 def _pathname(tempfile_or_path) -> str:
     if isinstance(tempfile_or_path, str):
-        return tempfile_or_path
+        return tempfile_or_path ################################################
     if isinstance(tempfile_or_path, yaltc.Recording):
-        return str(tempfile_or_path.AVpath)
+        return str(tempfile_or_path.AVpath) ####################################
     if isinstance(tempfile_or_path, Path):
-        return str(tempfile_or_path)
+        return str(tempfile_or_path) ###########################################
     if isinstance(tempfile_or_path, tempfile._TemporaryFileWrapper):
-        return tempfile_or_path.name
+        return tempfile_or_path.name ###########################################
     else:
         raise Exception('%s should be Path or tempfile...'%tempfile_or_path)
 
@@ -62,17 +64,12 @@ def _extr_channel(source, dest, channel):
     status = sox_transform.build(str(source), str(dest))
     logger.debug('sox status %s'%status)
 
-def _sox_keep(audio_file, kept_channels) -> tempfile.NamedTemporaryFile:
+def _sox_keep(audio_file, kept_channels: list) -> tempfile.NamedTemporaryFile:
     """
     Returns a NamedTemporaryFile containing the selected kept_channels
 
-    if len(kept_channels) == 1 then it's a mono mix on the specified track
-    if len(kept_channels) == 2 then it's a stereo mix on the specified tracks
+    Channels numbers in kept_channels are not ZBIDXed as per SOX format
     """
-
-
-
-
     audio_file = _pathname(audio_file)
     nchan = sox.file_info.channels(audio_file)
     logger.debug('in file of %i chan, have to keep %s'%
@@ -83,8 +80,8 @@ def _sox_keep(audio_file, kept_channels) -> tempfile.NamedTemporaryFile:
     # eg:   {1: [3], 2: [4]} to keep channels 3 & 4    
     kept_channels = [[n] for n in kept_channels]
     sox_remix_dict = dict(zip(all_channels, kept_channels))
-    output_fh = tempfile.NamedTemporaryFile(suffix='.wav', delete=DEL_TEMP)
-    out_file = _pathname(output_fh)
+    output_tempfile = tempfile.NamedTemporaryFile(suffix='.wav', delete=DEL_TEMP)
+    out_file = _pathname(output_tempfile)
     logger.debug('sox in and out files: %s %s'%(audio_file, out_file))
     # sox_transform.set_output_format(channels=1)
     sox_transform = sox.Transformer()
@@ -103,8 +100,7 @@ def _sox_keep(audio_file, kept_channels) -> tempfile.NamedTemporaryFile:
     stdout, stderr = p.communicate()
     logger.debug('remixed out_file ffprobe:\n%s'%(stdout +
         stderr).decode('utf-8'))
-    return output_fh
-
+    return output_tempfile
 
 def _split_channels(multi_chan_audio:Path) -> list:
     nchan = sox.file_info.channels(_pathname(multi_chan_audio))
@@ -132,7 +128,7 @@ def _sox_combine(paths) -> Path:
     """
     if len(paths) == 1: # one device only, nothing to stack
         logger.debug('one device only, nothing to stack')
-        return paths[0]
+        return paths[0] ########################################################
     out_file_handle = tempfile.NamedTemporaryFile(suffix='.wav',
         delete=DEL_TEMP)
     filenames = [_pathname(p) for p in paths]
@@ -158,29 +154,95 @@ def _sox_combine(paths) -> Path:
         (merged_duration, nchan))
     return out_file_handle
 
-def _sox_multi2mono(multichan_tmpfl) -> tempfile.NamedTemporaryFile:
-    # return a mono mix down
+def _sox_multi2stereo(multichan_tmpfl, stereo_trxs) -> tempfile.NamedTemporaryFile:
+
+    """
+    This mixes down all the tracks in multichan_tmpfl to a stereo wav file. Any
+    mono tracks are panned 50-50 (mono tracks are those not present in argument
+    stereo_trxs)
+
+    Args:
+        multichan_tmpfl : tempfile.NamedTemporaryFile
+            contains the edited and synced audio, almost ready to be merged
+            with the concurrent video file
+        stereo_trxs : list of pairs of integers
+            each pairs identifies a left-right tracks, 1st track in
+            multichan_tmpfl is index 1 (sox is not ZBIDX)
+    Returns:
+        the tempfile.NamedTemporaryFile of a stereo wav file
+        containing the audio to be merged with the video
+    """
     n_chan_input = sox.file_info.channels(_pathname(multichan_tmpfl))
     logger.debug('n chan input: %s'%n_chan_input)
     if n_chan_input == 1: # nothing to mix down
-        return multichan_tmpfl
-    mono_tpfl = tempfile.NamedTemporaryFile(suffix='.wav',
+        return multichan_tmpfl #################################################
+    stereo_tempfile = tempfile.NamedTemporaryFile(suffix='.wav',
                     delete=DEL_TEMP)
     tfm = sox.Transformer()
     tfm.channels(1)
-    status = tfm.build(_pathname(multichan_tmpfl),_pathname(mono_tpfl))
+    status = tfm.build(_pathname(multichan_tmpfl),_pathname(stereo_tempfile))
+    logger.debug('n chan ouput: %s'%
+                sox.file_info.channels(_pathname(stereo_tempfile)))
+    logger.debug('sox.build status for _sox_multi2stereo(): %s'%status)
+    if status != True:
+        print('Error, sox did not normalize file in _sox_multi2stereo()')
+        sys.exit(1)
+    return stereo_tempfile
+
+def _sox_mix_channels(multichan_tmpfl, stereo_pairs=[]) -> tempfile.NamedTemporaryFile:
+    """
+    Returns a mix down of the multichannel wav file. If stereo_pairs list is
+    empty, a mono mix is done with all the channel present in multichan_tmpfl.
+    If stereo_pairs contains one or more elements, a stereo mix is returned with
+    the specified Left-Right pairs and all other mono tracks (panned 50-50)
+
+    Note: stereo_pairs numbers are not ZBIDXed
+    """
+    n_chan_input = sox.file_info.channels(_pathname(multichan_tmpfl))
+    logger.debug('n chan input: %s'%n_chan_input)
+    if n_chan_input == 1: # nothing to mix down
+        return multichan_tmpfl #################################################
+    if stereo_pairs == []:
+        # all mono
+        mono_tpfl = tempfile.NamedTemporaryFile(suffix='.wav',
+                        delete=DEL_TEMP)
+        tfm = sox.Transformer()
+        tfm.channels(1)
+        status = tfm.build(_pathname(multichan_tmpfl),_pathname(mono_tpfl))
+        logger.debug('number of chan in ouput: %s'%
+                    sox.file_info.channels(_pathname(mono_tpfl)))
+        logger.debug('sox.build status for _sox_mix_channels(): %s'%status)
+        if status != True:
+            print('Error, sox did not normalize file in _sox_mix_channels()')
+            sys.exit(1)
+        return mono_tpfl
+    else:
+        # stereo tracks present, so stereo output
+        logger.debug('stereo tracks present %s, so stereo output'%stereo_pairs)
+        stereo_files = [_sox_keep(pair) for pair in stereo_pairs]
+    return 
+
+def _sox_mono2stereo(temp_file) -> tempfile.NamedTemporaryFile:
+    # upgrade a mono file to stereo panning 50-50
+    stereo_tempfile = tempfile.NamedTemporaryFile(suffix='.wav',
+                    delete=DEL_TEMP)
+    tfm = sox.Transformer()
+    tfm.channels(2)
+    status = tfm.build(_pathname(temp_file),_pathname(stereo_tempfile))
     logger.debug('n chan ouput: %s'%
-                sox.file_info.channels(_pathname(mono_tpfl)))
-    logger.debug('sox.build status for _sox_multi2mono(): %s'%status)
+                sox.file_info.channels(_pathname(stereo_tempfile)))
+    logger.debug('sox.build status for _sox_mono2stereo(): %s'%status)
     if status != True:
-        print('Error, sox did not normalize file in _sox_multi2mono()')
+        print('Error, sox did not normalize file in _sox_mono2stereo()')
         sys.exit(1)
-    return mono_tpfl
+    return stereo_tempfile
 
 
-def _sox_mix(paths:list) -> tempfile.NamedTemporaryFile:
+def _sox_mix_files(temp_files_to_mix:list) -> tempfile.NamedTemporaryFile:
     """
-    mix files referred by the list of Path into a new temporary files passed on return
+    Mix files referred by the list of Path into a new temporary files passed on
+    return. If one of the files is stereo, upgrade each mono file to a panned
+    50-50 stereo file before mixing.
     """
     def _sox_norm(tempf):
         normed_tempfile = tempfile.NamedTemporaryFile(suffix='.wav',
@@ -190,28 +252,42 @@ def _sox_mix(paths:list) -> tempfile.NamedTemporaryFile:
         status = tfm.build(_pathname(tempf),_pathname(normed_tempfile))
         logger.debug('sox.build status for norm(): %s'%status)
         if status != True:
-            print('Error, sox did not normalize file in _sox_mix()')
+            print('Error, sox did not normalize file in _sox_mix_files()')
             sys.exit(1)
         return normed_tempfile
-    paths = [_sox_norm(p) for p in paths]
-    cbn = sox.Combiner()
-    N = len(paths)
+    N = len(temp_files_to_mix)
     if N == 1: # nothing to mix
         logger.debug('one file: nothing to mix')
-        return paths[0]
+        return temp_files_to_mix[0] ########################################################
+    cbn = sox.Combiner()
     cbn.set_input_format(file_type=['wav']*N)
-    filenames = [_pathname(p) for p in paths]
-    logger.debug('%i files to mix %s'%(N, filenames))
-    logger.debug('nchan for each file %s'%[sox.file_info.channels(f) for
-                                    f in filenames])
+    # check if stereo files are present
+    max_n_chan = max([sox.file_info.channels(f) for f
+                                in [_pathname(p) for p in temp_files_to_mix]])
+    logger.debug('max_n_chan %s'%max_n_chan)
+    if max_n_chan == 2:
+        # upgrade all mono to stereo
+        stereo_tempfiles = [p for p in temp_files_to_mix
+            if sox.file_info.channels(_pathname(p)) == 2 ]
+        mono_tempfiles = [p for p in temp_files_to_mix
+            if sox.file_info.channels(_pathname(p)) == 1 ]
+        logger.debug('there are %i mono files and %i stereo files'%
+            (len(stereo_tempfiles), len(mono_tempfiles)))
+        new_stereo = [_sox_mono2stereo(tmpfl) for tmpfl
+                            in mono_tempfiles]
+        stereo_tempfiles += new_stereo
+        files_to_mix = [_pathname(tempfl) for tempfl in stereo_tempfiles]
+    else:
+        # all mono
+        files_to_mix = [_pathname(tempfl) for tempfl in temp_files_to_mix]
     mixed_tempf = tempfile.NamedTemporaryFile(suffix='.wav',delete=DEL_TEMP)
-    status = cbn.build(filenames,
+    status = cbn.build(files_to_mix,
                 _pathname(mixed_tempf),
                 combine_type='mix',
                 input_volumes=[1/N]*N)
     logger.debug('sox.build status for mix: %s'%status)
     if status != True:
-        print('Error, sox did not mix files in _sox_mix()')
+        print('Error, sox did not mix files in _sox_mix_files()')
         sys.exit(1)
     normed_tempfile = tempfile.NamedTemporaryFile(suffix='.wav',delete=DEL_TEMP)
     tfm = sox.Transformer()
@@ -219,16 +295,15 @@ def _sox_mix(paths:list) -> tempfile.NamedTemporaryFile:
     status = tfm.build(_pathname(mixed_tempf),_pathname(normed_tempfile))
     logger.debug('sox.build status for norm(): %s'%status)
     if status != True:
-        print('Error, sox did not normalize file in _sox_mix()')
+        print('Error, sox did not normalize file in _sox_mix_files()')
         sys.exit(1)
     return normed_tempfile
 
-
 class AudioStitcherVideoMerger:
     """
     Typically each found video is associated with an AudioStitcherVideoMerger
     instance. AudioStitcherVideoMerger does the actual audio-video file
-    processing of merging self.ref_recording (gen. a video) with all audio
+    processing of merging self.videoclip (gen. a video) with all audio
     files in  self.edited_audio as determined by the Matcher
     object (it instanciates and manages AudioStitcherVideoMerger objects).
 
@@ -237,15 +312,15 @@ class AudioStitcherVideoMerger:
     devices to match the precise clock value of the ref recording (to a few
     ppm), using sox tempo transform.
 
-    N.B.: A audio_stitch doesn't extend beyond the corresponding ref_recording
+    N.B.: A audio_stitch doesn't extend beyond the corresponding videoclip
     video start and end times: it is not a audio montage for the whole movie
     project.
 
 
     Attributes:
 
-        ref_recording : a Recording instance
-            The video (or designated main sound) audio files are synced to
+        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
@@ -259,19 +334,19 @@ class AudioStitcherVideoMerger:
 
     """
 
-    def __init__(self, reference_recording):
-        self.ref_recording = reference_recording
+    def __init__(self, video_clip):
+        self.videoclip = video_clip
         # self.matched_audio_recordings = []
         self.edited_audio = {}
         logger.debug('instantiating AudioStitcherVideoMerger for %s'%
-                            reference_recording)
+                            video_clip)
 
     def add_matched_audio(self, audio_rec):
         """
         Populates self.edited_audio, a dict as {Recording : path}
 
         AudioStitcherVideoMerger.add_matched_audio() is called
-        within Matcher.scan_audio_for_each_ref_rec()
+        within Matcher.scan_audio_for_each_videoclip()
 
         Returns nothing, fills self.edited_audio dict with
         matched audio.
@@ -290,7 +365,7 @@ class AudioStitcherVideoMerger:
 
     def get_matched_audio_recs(self):
         """
-        Returns audio recordings that overlap self.ref_recording.
+        Returns audio recordings that overlap self.videoclip.
         Simply keys of self.edited_audio dict
         """
         return list(self.edited_audio.keys())
@@ -315,14 +390,14 @@ class AudioStitcherVideoMerger:
         sox_transform = sox.Transformer()
         # tempo_scale_factor = rec.device_relative_speed
         tempo_scale_factor = rec.device_relative_speed
-        reC_dev = rec.device.name
-        reF_dev = self.ref_recording.device.name
+        audio_dev = rec.device.name
+        video_dev = self.videoclip.device.name
         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'%
-                (reC_dev, reF_dev, tempo_scale_factor))
+                (audio_dev, video_dev, tempo_scale_factor))
         else:
             print('[gold1]%s[/gold1] clock too slow relative to [gold1]%s[/gold1] so file is too short by a %f factor\n'%
-                (reC_dev, reF_dev, tempo_scale_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)
@@ -347,11 +422,11 @@ class AudioStitcherVideoMerger:
         # 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 reference rec %s:'%(len(recordings),
-            self.ref_recording))
+        logger.debug('%i audio files for videoclip %s:'%(len(recordings),
+            self.videoclip))
         for r in recordings:
             logger.debug('  %s'%r)
-        speeds = numpy.array([rec.get_speed_ratio(self.ref_recording)
+        speeds = numpy.array([rec.get_speed_ratio(self.videoclip)
                                     for rec in recordings])
         mean_speed = numpy.mean(speeds)
         for r in recordings:
@@ -359,9 +434,9 @@ class AudioStitcherVideoMerger:
             # 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.ref_recording)
+            r.set_time_position_to(self.videoclip)
             logger.debug('time_position for %s: %fs relative to %s'%(r,
-                r.time_position, self.ref_recording))
+                r.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,
@@ -427,7 +502,7 @@ class AudioStitcherVideoMerger:
         end_time = sox.file_info.duration(growing_file.name)
         logger.debug('total edited audio duration  %.2f s'%end_time)
         logger.debug('video duration  %.2f s'%
-            self.ref_recording.get_duration())
+            self.videoclip.get_duration())
         return growing_file
 
     def _pad_or_trim_first_audio(self, first_rec):
@@ -436,17 +511,17 @@ class AudioStitcherVideoMerger:
         NO: will change tempo after trimming/padding
 
         Store (into Recording.edited_audio dict) the handle  of the sox processed
-        first recording, padded or chopped according to AudioStitcherVideoMerger.ref_recording
+        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
         transform, so check it with sox.file_info.duration()
         """
         logger.debug(' editing %s'%first_rec)
         audio_start  = first_rec.get_start_time()
-        ref_start = self.ref_recording.get_start_time()
-        if ref_start < audio_start: # padding
+        video_start = self.videoclip.get_start_time()
+        if video_start < audio_start: # padding
             logger.debug('padding')
-            pad_duration  = (audio_start-ref_start).total_seconds()
+            pad_duration  = (audio_start-video_start).total_seconds()
             """padding first_file:
                     ┏━━━━━━━━━━━━━━━┓
                     ┗━━━━━━━━━━━━━━━┛ref
@@ -456,7 +531,7 @@ class AudioStitcherVideoMerger:
             self._pad_file(first_rec, pad_duration)
         else:
             logger.debug('trimming')
-            length = (ref_start-audio_start).total_seconds()
+            length = (video_start-audio_start).total_seconds()
             """chopping first_file:
                     ┏━━━━━━━━━━━━━━━┓
                     ┗━━━━━━━━━━━━━━━┛ref
@@ -505,7 +580,7 @@ class AudioStitcherVideoMerger:
         logger.debug('transform: %s'%sox_transform.effects)
         recording_fh = self.edited_audio[audio_rec]
         logger.debug('for recording %s, matching %s'%(audio_rec,
-                                                self.ref_recording))
+                                                self.videoclip))
         input_file = _pathname(recording_fh)
         logger.debug('AudioStitcherVideoMerger.edited_audio[audio_rec]: %s'%
                                                     input_file)
@@ -551,7 +626,7 @@ class AudioStitcherVideoMerger:
             """         
             sox_transform = sox.Transformer()
             audio_length = sox.file_info.duration(_pathname(audio_tempfile))
-            video_length = self.ref_recording.get_duration()
+            video_length = self.videoclip.get_duration()
             if audio_length > video_length:
                 # trim audio
                 sox_transform.trim(0, video_length)
@@ -570,9 +645,9 @@ class AudioStitcherVideoMerger:
             logger.debug('audio duration  %.2f s'%
                 sox.file_info.duration(_pathname(out_tf)))
             logger.debug('video duration  %.2f s'%
-                self.ref_recording.get_duration())
+                self.videoclip.get_duration())
             return out_tf
-        synced_clip_file = self.ref_recording.final_synced_file
+        synced_clip_file = self.videoclip.final_synced_file
         synced_clip_dir = synced_clip_file.parent
         # build ISOs subfolders structure, see comment string below
         video_stem_WO_suffix = synced_clip_file.stem
@@ -591,75 +666,148 @@ class AudioStitcherVideoMerger:
             mono_tmpfl_trimpad = _fit_length(mono_tmpfl)
             shutil.copy(_pathname(mono_tmpfl_trimpad), destination)
             logger.debug('destination:%s'%destination)
-        # # mixNnormed = _sox_mix(tempfiles)
+        # # mixNnormed = _sox_mix_files(tempfiles)
         # # print('516', _pathname(mixNnormed))
         # os.remove(ISO_multi_chan)
 
-    def _get_mix(self, device, multichan_tmpfl) -> tempfile.NamedTemporaryFile:
-        """        
-        If device has an associated Tracks description that declares a (mono or
-        stereo) mix track, returns a tmpfl containing the corresponding
-        tracks. If not, mix all the tracks with sox.
+    def _get_device_mix(self, device, multichan_tmpfl) -> tempfile.NamedTemporaryFile:
+        """
+        Build or get a mix from edited and joined audio for a given device
+
+        Returns a mix for merging with video clip. The way the mix is obtained
+        (or created) depends if a tracks.txt for the device  was submitted and
+        depends on its content. There are 4 cases (explained later):
+
+        #1 no mix (or no tracks.txt), all mono
+        #2 no mix, one or more stereo mics
+        #3 mono mix declared
+        #4 stereo mix declared
+
+        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:
+
+            #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
+        stereo) mix track, this fct returns a tempfile containing the
+        corresponding tracks, simpley extarcting them from multichan_tmpfl
+        (thos covers cases #3 and #4)
+
+        Args:
+            device : device_scanner.Device dataclass
+                the device that recorded the audio found in multichan_tmpfl
+            multichan_tmpfl : tempfile.NamedTemporaryFile
+                contains the edited and synced audio, almost ready to be merged
+                with the concurrent video file (after mix down)
+
+        Returns:
+            the tempfile.NamedTemporaryFile of a stereo or mono wav file
+            containing the audio to be merged with the video in
+            self.videoclip
 
-        If no L-R tracks are declared in tracks.txt, a mono mix is returned;
-        If some
-        micL micR or mixL mixR
 
         """
-        if device.tracks is None:
-            logger.debug('no tracks.txt, mixing all')
-            return _sox_multi2mono(multichan_tmpfl)
-        mix_tracks = device.tracks.mix
-        if mix_tracks == []:
-            logger.debug('tracks.txt present but no mix trx, mixing all')
-            return _sox_multi2mono(multichan_tmpfl)
-        # if here, mix exists
-        logger.debug('%s has mix %s'%(device.name, mix_tracks))
         logger.debug('device %s'%device)
-        if 'ttc' in device.tracks.rawtrx:
-            sox_TTC_chan = device.tracks.rawtrx.index('ttc')
-        elif 'tc' in device.tracks.rawtrx:
-            sox_TTC_chan = device.tracks.rawtrx.index('tc')
-        else:
-            print('Error: no tc or ttc tag in track.txt')
+        if device.n_chan == 2:
+            # tracks.txt or not,
+            # it's stereo, ie audio + TTC, so remove TTC and return
+            kept_channel = (device.ttc + 1)%2 # 1 -> 0 and 0 -> 1
+            logger.debug('no tracks.txt, keeping one chan %i'%kept_channel)
+            return _sox_keep(multichan_tmpfl, [kept_channel + 1]) #-------------
+        logger.debug('device.n_chan != 2, so multitrack')
+        # it's multitrack (more than 2 channels)
+        if device.tracks is None:
+            # multitrack but no mix done on location, so do mono mix with all
+            all_channels = list(range(device.n_chan))
+            logger.debug('multitrack but no tracks.txt, mixing %s except TTC at %i'%
+                (all_channels, device.ttc))
+            all_channels.remove(device.ttc)
+            sox_kept_channels = [i + 1 for i in all_channels] # sox indexing
+            logger.debug('mixing channels: %s (sox #)'%sox_kept_channels)
+            kept_audio = _sox_keep(multichan_tmpfl, sox_kept_channels)
+            return _sox_mix_channels(kept_audio) #------------------------------
+        logger.debug('there IS a device.tracks')
+        # user wrote a tracks.txt metadata file, check it to get the mix(or do
+        # it). But first a check is done if the ttc tracks concur: the track
+        # detected by the Decoder class, stored in device.ttc VS the track
+        # declared by the user, device.tracks.ttc (see device_scanner.py). If
+        # not, warn the user and exit.
+        logger.debug('ttc channel declared for the device: %i, ttc detected: %i, non zero base indexing'%
+                        (device.ttc, device.tracks.ttc))
+        if device.ttc + 1 != device.tracks.ttc: # warn and quit
+            print('Error: TicTacCode channel detected is [gold1]%i[/gold1]'%
+                device.ttc + 1, end=' ')
+            print('and the file [gold1]%s[/gold1] specifies channel [gold1]%i[/gold1],'%
+                (device_scanner.TRACKSFN, device.tracks.ttc))
+            print('Please correct the discrepancy and rerun. Quitting.')
+            sys.exit(1)
+        if device.tracks.mix == [] and device.tracks.stereomics == []:
+            # it's multitrac and no mix done on location, so do a mono mix with
+            # all, but here remove '0' and TTC tracks from mix
+            all_channels = list(range(1, device.n_chan + 1)) # sox not ZBIDX
+            to_remove = device.tracks.unused + [device.ttc+1]# unused is sox idx
+            logger.debug('multitrack but no tracks.txt, mixing %s except # %s (sox #)'%
+                (all_channels, to_remove))
+            sox_kept_channels = [i for i in all_channels
+                                            if i not in to_remove]
+            logger.debug('mixing channels: %s (sox #)'%sox_kept_channels)
+            kept_audio = _sox_keep(multichan_tmpfl, sox_kept_channels)
+            return _sox_mix_channels(kept_audio) #------------------------------
+        logger.debug('device.tracks.mix != [] or device.tracks.stereomics != []')
+        if device.tracks.mix != []:
+            # Mix were done on location, no and we only have to extracted it
+            # from the recording. If mono mix, device.tracks.mix has one element;
+            # if stereo mix, device.tracks.mix is a pair of number:
+            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:
+                trx_TTC_chan = device.tracks.rawtrx.index('tc')
+            else:
+                print('Error: no tc or ttc tag in track.txt')
+                sys.exit(1)
+            logger.debug('TTC chan %i, dev ttc %i'%(trx_TTC_chan, device.ttc))
+            if trx_TTC_chan != device.ttc:
+                print('Error: ttc channel # incoherency in track.txt')
+                sys.exit(1)
+            # coherency check done, extract mix track (or tracks if stereo)
+            mix_kind = 'mono' if len(device.tracks.mix) == 1 else 'stereo'
+            logger.debug('%s mix declared on channel %s (sox #)'%
+                    (mix_kind, device.tracks.mix))
+            return _sox_keep(multichan_tmpfl, device.tracks.mix) #--------------
+        logger.debug('device.tracks.mix == []')
+        # if here, all cases have been covered, all is remaining is this case:
+        # tracks.txt exists  AND there is no mix AND stereo mic(s) so first a
+        # coherency check, and then proceed
+        if device.tracks.stereomics == []:
+            print('Error, no stereo mic?, check tracks.txt. Quitting')
             sys.exit(1)
-        sox_TTC_chan += 1 # sox Not ZBIDX
-        logger.debug('TTC chan %i'%sox_TTC_chan)
-        # redo indexing since tracks.txt numbers refere to complete
-        # files and here audio file had TTC and muted channels
-        # removed:
-        if len(mix_tracks) == 2: # two tracks to shift
-            mixL_chan, mixR_chan = mix_tracks
-            # shifting left chan if necessary
-            shift = 0
-            if mixL_chan > sox_TTC_chan:
-                shift += 1
-            for unused_tr in device.tracks.unused:
-                if mixL_chan > unused_tr:
-                    shift += 1
-            mixL_chan -= shift
-            # shifting right chan if necessary
-            shift = 0
-            if mixR_chan > sox_TTC_chan:
-                shift += 1
-            for unused_tr in device.tracks.unused:
-                if mixR_chan > unused_tr:
-                    shift += 1
-            mixR_chan -= shift
-            mix_tracks = [mixL_chan, mixR_chan]
-        else: # mono, one track to shift
-            monomix_chan = mix_tracks[0]
-            shift = 0
-            if monomix_chan > sox_TTC_chan:
-                shift += 1
-            for unused_tr in device.tracks.unused:
-                if monomix_chan > unused_tr:
-                    shift += 1
-            monomix_chan -= shift
-            mix_tracks = [monomix_chan]
-        logger.debug('new mix_tracks: %s'%mix_tracks)
-        return _sox_keep(multichan_tmpfl, mix_tracks)
-            
+        logger.debug('processing stereo pair(s) %s'%device.tracks.stereomics)
+        stereo_mic_idx_pairs = [pair for name, pair in device.tracks.stereomics]
+        logger.debug('stereo pairs idxs %s'%stereo_mic_idx_pairs)
+        mic_stereo_files = [_sox_keep(multichan_tmpfl, pair) for pair
+                                                    in stereo_mic_idx_pairs]
+        # flatten list of tuples of channels being stereo mics
+        stereo_mic_idx_flat = [item for sublist in stereo_mic_idx_pairs
+                                                    for item in sublist]
+        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)
+        # remove TTC track number
+        mono_tracks.remove(device.ttc + 1)
+        logger.debug('mono_tracks %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,
                                     write_multicam_structure,
@@ -674,7 +822,7 @@ class AudioStitcherVideoMerger:
 
         asked_ISOs: bool flag specified as CLI argument
 
-        For each audio devices found overlapping self.ref_recording: pad, trim
+        For each audio devices found overlapping self.videoclip: 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
@@ -686,8 +834,8 @@ class AudioStitcherVideoMerger:
         """
         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.ref_recording,
-            self.ref_recording.device))
+        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):
         if output_dir == None:
@@ -695,56 +843,72 @@ class AudioStitcherVideoMerger:
         else:
             synced_clip_dir = Path(output_dir)/Path(top_dir).name # = somefolder/mondayPM
         if write_multicam_structure:
-            device_name = self.ref_recording.device.name
+            device_name = self.videoclip.device.name
             synced_clip_dir = synced_clip_dir/device_name # = synced_clip_dir/ZOOM
         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.ref_recording.new_rec_name).name
+            Path(self.videoclip.new_rec_name).name
         logger.debug('editing files for %s'%synced_clip_file)
-        self.ref_recording.final_synced_file = synced_clip_file # relative
-        # collecting edited audio by device, in (Device, tempfile) pairs:
+        self.videoclip.final_synced_file = synced_clip_file # relative path
+        # Collecting edited audio by device, in (Device, tempfile) 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()]
         if len(merged_audio_files_by_device) == 0:
             # no audio file overlaps for this clip
-            return
+            return #############################################################
         if len(merged_audio_files_by_device) == 1:
             # only one audio recorder was used, pick singleton in list
             dev, concatenate_audio_file = merged_audio_files_by_device[0]
             logger.debug('one audio device only: %s'%dev)
             # check if this sole recorder is stereo
             if dev.n_chan == 2:
-                # stereo minus TTC chan = mono, check consistency:
+                # consistency check
                 nchan_sox = sox.file_info.channels(
                     _pathname(concatenate_audio_file))
-                logger.debug('nchan_sox: %i mono?'%nchan_sox)
-                if not nchan_sox == 1:
+                logger.debug('Two chan only, nchan_sox: %i dev.n_chan %i'%
+                                (nchan_sox, dev.n_chan))
+                if not nchan_sox == 2:
                     raise Exception('Error in channel processing')
                 # all OK, merge and return
-                logger.debug('simply mono to merge')
-                self.ref_recording.synced_audio = concatenate_audio_file
+                logger.debug('simply mono to merge, TTC on chan %i'%
+                            dev.ttc)
+                # only 2 channels so keep the channel OTHER than TTC
+                if dev.ttc == 1:
+                    # keep channel 0, but + 1 because of sox indexing
+                    sox_kept_channel = 1 
+                else:
+                    # dev.ttc == 0 so keep ch 1, but + 1 (sox indexing)
+                    sox_kept_channel = 2
+                self.videoclip.synced_audio = \
+                        _sox_keep(concatenate_audio_file, [sox_kept_channel])
                 self._merge_audio_and_video()
-                return
-        # if still here, either multitracks and/or multi recorders so check if a
-        # mix has been done on location and identified as is in atracks.txt
-        # file. Split audio channels in mono wav tempfiles at the same time
+                return #########################################################
+        #
+        # if not returned yet from fct, either multitracks and/or multi
+        # recorders so check if a mix has been done on location and identified
+        # as is in atracks.txt file. Split audio channels in mono wav tempfiles
+        # at the same time
         #
         multiple_recorders = len(merged_audio_files_by_device) > 1
         logger.debug('multiple_recorder: %s'%multiple_recorders)
-        # dev_mixes_mix contains all audio recorders if many
-        mixes = [self._get_mix(device, multi_chan_audio)
+        # the device_mixes list contains all audio recorders if many. If only
+        # one audiorecorder was used (most of the cases) len(device_mixes) is 1
+        device_mixes = [self._get_device_mix(device, multi_chan_audio)
                 for device, multi_chan_audio
                 in merged_audio_files_by_device]
-        logger.debug('there are %i dev mixes'%len(mixes))
-        logger.debug('mixes %s'%mixes)
-        dev_mixes_mix = _sox_mix(mixes)
-        logger.debug('will merge with %s'%(_pathname(dev_mixes_mix)))
-        self.ref_recording.synced_audio = dev_mixes_mix
-        logger.debug('dev_mixes_mix n chan: %i'%
-            sox.file_info.channels(_pathname(dev_mixes_mix)))
+        logger.debug('there are %i dev device_mixes'%len(device_mixes))
+        logger.debug('device_mixes %s'%device_mixes)
+        mix_of_device_mixes = _sox_mix_files(device_mixes)
+        logger.debug('will merge with %s'%(_pathname(mix_of_device_mixes)))
+        self.videoclip.synced_audio = mix_of_device_mixes
+        logger.debug('mix_of_device_mixes n chan: %i'%
+            sox.file_info.channels(_pathname(mix_of_device_mixes)))
         self._merge_audio_and_video()
         # devices_and_monofiles is list of (device, [monofiles])
         # [(dev1, multichan1), (dev2, multichan2)] in
@@ -757,24 +921,28 @@ class AudioStitcherVideoMerger:
                     in merged_audio_files_by_device]
             logger.debug('devices_and_monofiles: %s'%
                 pprint.pformat(devices_and_monofiles))
-            def _trnm(dev, idx): # used in the list comprehension just below
+            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:
                     tag = '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 = audio_tags[idx]
+                    # audio_tags = [tag for tag in dev.tracks.rawtrx
+                    #     if tag not in ['ttc','0','tc']]
+                    tag = dev.tracks.rawtrx[idx]
                 if multiple_recorders:
                     tag += '_' + dev.name
-                return tag
+                logger.debug('tag %s'%tag)
+                return tag #####################################################
             # 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):
-                    names_audio_tempfiles.append((_trnm(dev, idx), monotf))
+                    track_name = _trnm(dev, idx)
+                    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'%
@@ -804,25 +972,24 @@ class AudioStitcherVideoMerger:
         out1 = in1.output(file_handle.name, map='0:v', vcodec='copy')
         ffmpeg.run([out1.global_args(*silenced_opts)], overwrite_output=True)
         return file_handle
-        # os.path.split audio channels if more than one
 
     def _merge_audio_and_video(self):
         """      
-        Calls ffmpeg to join video in self.ref_recording.AVpath to
-        audio in self.ref_recording.synced_audio
+        Calls ffmpeg to join video in self.videoclip.AVpath to
+        audio in self.videoclip.synced_audio
 
-        On entry, ref_recording.final_synced_file is a Path to an non existing
-        file (contrarily to ref_recording.synced_audio).
-        On exit, self.ref_recording.final_synced_file points to the final synced
+        On entry, videoclip.final_synced_file is a Path to an non existing
+        file (contrarily to videoclip.synced_audio).
+        On exit, self.videoclip.final_synced_file points to the final synced
         video file.
 
         Returns nothing.
         """
-        synced_clip_file = self.ref_recording.final_synced_file
-        video_path = self.ref_recording.AVpath
-        timecode = self.ref_recording.get_timecode()
-        # self.ref_recording.synced_audio = audio_path
-        audio_path = self.ref_recording.synced_audio
+        synced_clip_file = self.videoclip.final_synced_file
+        video_path = self.videoclip.AVpath
+        timecode = self.videoclip.get_timecode()
+        # self.videoclip.synced_audio = audio_path
+        audio_path = self.videoclip.synced_audio
         vid_only_handle = self._keep_VIDEO_only(video_path)
         a_n = _pathname(audio_path)
         v_n = str(vid_only_handle.name)
@@ -876,20 +1043,10 @@ class Matcher:
     AudioStitcherVideoMerger objects that do the actual file manipulations. Each video
     (and main sound) will have its AudioStitcherVideoMerger instance.
 
-    All videos are de facto reference recording and matching audio files are
-    looked up for each one of them.
-
     The Matcher doesn't keep neither set any editing information in itself: the
     in and out time values (UTC times) used are those kept inside each Recording
     instances.
 
-    [NOT YET IMPLEMENTED]: When shooting is done with multiple audio recorders,
-    ONE audio device can be designated as 'main sound' and used as reference
-    recording; then all audio tracks are synced together against this main
-    sound audio file, keeping the TicTacCode track alongside for syncing against
-    their video counterpart(in a second pass and after a mixdown editing).
-    [/NOT YET IMPLEMENTED]
-
     Attributes:
 
         recordings : list of Recording instances
@@ -897,7 +1054,7 @@ class Matcher:
 
         video_mergers : list
             of AudioStitcherVideoMerger Class instances, built by
-            scan_audio_for_each_ref_rec(); each video has a corresponding
+            scan_audio_for_each_videoclip(); each video has a corresponding
             AudioStitcherVideoMerger object. An audio_stitch doesn't extend
             beyond the corresponding video start and end times.
 
@@ -929,7 +1086,7 @@ class Matcher:
                 _pathname(rec.AVpath),
                 _pathname(rec.new_rec_name)))
 
-    def scan_audio_for_each_ref_rec(self):
+    def scan_audio_for_each_videoclip(self):
         """
         For each video (and for the Main Sound) in self.recordings, this finds
         any audio that has overlapping times and instantiates a
@@ -940,21 +1097,21 @@ class Matcher:
         V3 checked against    ...
         Main Sound checked against A1, A2, A3, A4
         """
-        refeference_recordings = [r for r in self.recordings if r.is_video()
+        video_recordings = [r for r in self.recordings if r.is_video()
                                                             or r.is_reference]
         audio_recs = [r for r in self.recordings if r.is_audio()
                                                 and not r.is_reference]
         if not audio_recs:
             print('\nNo audio recording found, syncing of videos only not implemented yet, exiting...\n')
             sys.exit(1)
-        for ref_rec in refeference_recordings:
-            reference_tag = 'video' if ref_rec.is_video() else 'audio'
+        for videoclip in video_recordings:
+            reference_tag = 'video' if videoclip.is_video() else 'audio'
             logger.debug('Looking for overlaps with %s %s'%(
                             reference_tag,
-                            ref_rec))
-            audio_stitch = AudioStitcherVideoMerger(ref_rec)
+                            videoclip))
+            audio_stitch = AudioStitcherVideoMerger(videoclip)
             for audio in audio_recs:
-                if self._does_overlap(ref_rec, audio):
+                if self._does_overlap(videoclip, audio):
                     audio_stitch.add_matched_audio(audio)
                     logger.debug('recording %s overlaps,'%(audio))
                     # print('  recording [gold1]%s[/gold1] overlaps,'%(audio))
@@ -962,13 +1119,13 @@ class Matcher:
                 self.video_mergers.append(audio_stitch)
             else:
                 logger.debug('\n  nothing\n')
-                print('No overlap found for %s'%ref_rec.AVpath.name)
+                print('No overlap found for %s'%videoclip.AVpath.name)
                 del audio_stitch
         logger.debug('%i video_mergers created'%len(self.video_mergers))
 
-    def _does_overlap(self, ref_rec, audio_rec):
+    def _does_overlap(self, videoclip, audio_rec):
         A1, A2 = audio_rec.get_start_time(), audio_rec.get_end_time()
-        R1, R2 = ref_rec.get_start_time(), ref_rec.get_end_time()
+        R1, R2 = videoclip.get_start_time(), videoclip.get_end_time()
         no_overlap = (A2 < R1) or (A1 > R2)
         return not no_overlap
 
@@ -990,11 +1147,11 @@ class Matcher:
         Returns nothing, changes are done in the video files metadata
         (each referenced by Recording.final_synced_file)
         """
-        vids = [m.ref_recording for m in self.video_mergers]
+        vids = [m.videoclip for m in self.video_mergers]
         logger.debug('vids %s'%vids)
         if len(vids) == 1:
             logger.debug('just one take, no gap to shrink')
-            return
+            return #############################################################
         # INs_and_OUTs contains (time, direction, video) for each video,
         # where direction is 'in|out' and video an instance of Recording
         INs_and_OUTs = [(vid.get_start_time(), 'in', vid) for vid in vids]