Updating requirements, removing ear

Create LICENSE

.python-version

@@ -0,0 +1 @@
+3.11.12

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2020, Jamie Hardt
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,7 +1,16 @@
 # soundobjects Blender Add-On
 
-This add-on adds three operators for working with immersive 3D audio in [Blender][blender], specifically it allows you to create ADM Broadcast
-WAVE files for use with [Dolby Atmos][atmos] or other object-based sound mixing workflows.
+**NOTE**: _Avid made some changes to ADM file import in Pro Tools and it no
+longer accepts ADMs made by this plugin. It may still work with other DAWs._
+
+This add-on adds three operators for working with immersive 3D audio in
+[Blender][blender], specifically it allows you to create ADM Broadcast WAVE
+files for use with [Dolby Atmos][atmos] or other object-based sound mixing
+workflows.
+
+[Here](https://vimeo.com/464569386) you can see a short demo of how to add
+sounds to an animated Blender scene and import the resulting file into Pro
+Tools and then play them into a Dolby DAPS Renderer.
 
 [blender]: https://www.blender.org
 [atmos]: https://www.dolby.com/technologies/dolby-atmos/
@@ -10,25 +19,32 @@ WAVE files for use with [Dolby Atmos][atmos] or other object-based sound mixing
 
 ### `import_test.wav_file_batch`
 
-**Import WAV Files:** This operator allows you to add multiple audio files to a .blend file so they'll be available to
-the *Add Sounds to Meshes* operator.
+**Import WAV Files:** This operator allows you to add multiple audio files to a
+.blend file so they'll be available to the *Add Sounds to Meshes* operator.
 
 ### `object.add_speakers_to_obj`
 
-**Add Sounds to Meshes:** This operator takes all the selected objects in the current scene and attaches a new speaker 
-locked to that object's location throughout the animation. You provide the prefix for the name of a set of sound files
-added with the _Import WAV Files_ operator, and these are added to each selected object randomly. The sounds can be 
-timed to either begin playing at the beginning of the sequence, at a random time, or when the respective object is
+**Add Sounds to Meshes:** This operator takes all the selected objects in the
+current scene and attaches a new speaker locked to that object's location
+throughout the animation. You provide the prefix for the name of a set of sound
+files
+added with the _Import WAV Files_ operator, and these are added to each
+selected object randomly. The sounds can be timed to either begin playing at
+the beginning of the sequence, at a random time, or when the respective object
+is
 closest to the scene's camera.
 
 ### `export.adm_wave_file`
 
-**Export ADM Wave File:** This operator exports all of the speakers in a scene as an ADM Broadcast-WAV file compartible
-with a Dolby Atmos rendering workflow. This produces a multichannel WAV file with embedded ADM metadata the passes
-panning information to the client. (Has been tested and works with Avid Pro Tools 2020).
+**Export ADM Wave File:** This operator exports all of the speakers in a scene
+as an ADM Broadcast-WAV file compartible with a Dolby Atmos rendering workflow.
+This produces a multichannel WAV file with embedded ADM metadata the passes
+panning information to the client. (Has been tested and works with Avid Pro
+Tools 2020).
 
 
-## Important Note
+## Requirements
 
-This add-on requires that the [EBU Audio Renderer](https://github.com/ebu/ebu_adm_renderer) (`ear` v2.0) Python package 
+This add-on requires that the [EBU Audio
+Renderer](https://github.com/ebu/ebu_adm_renderer) (`ear` v2.0) Python package
 be installed to Blender's Python.

__init__.py

@@ -10,13 +10,25 @@ bl_info = {
     "author": "Jamie Hardt",
     "version": (0, 1),
     "warning": "Requires `ear` EBU ADM Renderer package to be installed",
-    "blender": (2, 90, 0),
+    "blender": (2, 93, 1),
     "category": "Import-Export",
     "support": "TESTING",
     "tracker_url": "https://github.com/iluvcapra/soundobjects_blender_addon/issues",
     "wiki_url": ""
 }
 
+# class SoundObjectAttachmentPanel(bpy.types.Panel):
+#    bl_idname = "OBJECT_PT_sound_object_attachment_panel"
+#    bl_space_type = "VIEW_3D"
+#    bl_label = "Attach Sounds"
+#    bl_region_type = "UI"
+#    bl_category = "Tools"
+#    bl_context = "object"
+#    bl_options = {"DEFAULT_CLOSED"}
+
+#    def draw(self, context):
+#        self.layout.label(text="Attach Sounds")
+
 
 def import_wav_menu_callback(self, context):
     self.layout.operator(ImportWav.bl_idname, text="WAV Audio Files (.wav)")
@@ -39,7 +51,7 @@ def register():
     bpy.types.TOPBAR_MT_file_export.append(export_adm_menu_callback)
     bpy.types.VIEW3D_MT_object.append(add_sound_to_mesh_menu_callback)
 
-    bpy.utils.register_class(SoundObjectAttachmentPanel)
+#    bpy.utils.register_class(SoundObjectAttachmentPanel)
     
 
 def unregister():
@@ -51,4 +63,4 @@ def unregister():
     bpy.types.TOPBAR_MT_file_export.remove(export_adm_menu_callback)
     bpy.types.VIEW3D_MT_object.remove(add_sound_to_mesh_menu_callback)
 
-    bpy.utils.unregister_class(SoundObjectAttachmentPanel)
+#    bpy.utils.unregister_class(SoundObjectAttachmentPanel)

intern/add_sound_to_meshes.py

@@ -1,8 +1,10 @@
 import bpy
 from numpy.linalg import norm
+from numpy.typing import ArrayLike
 from random import uniform, gauss
 from math import floor
 from enum import Enum
+from typing import cast
 
 from dataclasses import dataclass
 
@@ -27,7 +29,8 @@ class SpatialEnvelope:
     exits_range: int
 
 
-def sound_camera_spatial_envelope(scene: bpy.types.Scene, speaker_obj, considered_range: float) -> SpatialEnvelope:
+def sound_camera_spatial_envelope(scene: bpy.types.Scene, speaker_obj,
+                                  considered_range: float) -> SpatialEnvelope:
     min_dist = sys.float_info.max
     min_dist_frame = scene.frame_start
     enters_range_frame = None
@@ -35,8 +38,10 @@ def sound_camera_spatial_envelope(scene: bpy.types.Scene, speaker_obj, considere
 
     in_range = False
     for frame in range(scene.frame_start, scene.frame_end + 1):
+        assert scene.camera
         scene.frame_set(frame)
-        rel = speaker_obj.matrix_world.to_translation() - scene.camera.matrix_world.to_translation()
+        rel = speaker_obj.matrix_world.to_translation() \
+            - scene.camera.matrix_world.to_translation()
         dist = norm(rel)
 
         if dist < considered_range and not in_range:
@@ -44,7 +49,7 @@ def sound_camera_spatial_envelope(scene: bpy.types.Scene, speaker_obj, considere
             in_range = True
 
         if dist < min_dist:
-            min_dist = dist
+            min_dist = float(dist)
             min_dist_frame = frame
 
         if dist > considered_range and in_range:
@@ -52,6 +57,9 @@ def sound_camera_spatial_envelope(scene: bpy.types.Scene, speaker_obj, considere
             in_range = False
             break
 
+    assert enters_range_frame
+    assert exits_range_frame
+
     return SpatialEnvelope(considered_range=considered_range,
                            enters_range=enters_range_frame,
                            exits_range=exits_range_frame,
@@ -59,13 +67,20 @@ def sound_camera_spatial_envelope(scene: bpy.types.Scene, speaker_obj, considere
                            min_distance=min_dist)
 
 
-def closest_approach_to_camera(scene, speaker_object):
+def closest_approach_to_camera(scene: bpy.types.Scene, 
+                               speaker_object: bpy.types.Object) -> tuple[float, int]:
+    """
+    Steps through the scene frame-by-frame and returns a tuple of 
+    (minumum_distance, at_frame_index)
+    """
     max_dist = sys.float_info.max
     at_time = scene.frame_start
     for frame in range(scene.frame_start, scene.frame_end + 1):
+        assert scene.camera
         scene.frame_set(frame)
-        rel = speaker_object.matrix_world.to_translation() - scene.camera.matrix_world.to_translation()
-        dist = norm(rel)
+        rel = speaker_object.matrix_world.to_translation() - \
+                scene.camera.matrix_world.to_translation()
+        dist = float(norm(cast(ArrayLike, rel)))
 
         if dist < max_dist:
             max_dist = dist
@@ -74,7 +89,7 @@ def closest_approach_to_camera(scene, speaker_object):
     return (max_dist, at_time)
 
 
-def track_speaker_to_camera(speaker, camera):
+def track_speaker_to_camera(speaker):
     camera_lock = speaker.constraints.new('TRACK_TO')
     camera_lock.target = bpy.context.scene.camera
     camera_lock.use_target_z = True
@@ -89,7 +104,8 @@ def spot_audio(context, speaker, trigger_mode, sync_peak, sound_peak, sound_leng
         audio_scene_in = envelope.closest_range
 
     elif trigger_mode == TriggerMode.RANDOM:
-        audio_scene_in = floor(uniform(context.scene.frame_start, context.scene.frame_end))
+        audio_scene_in = floor(
+            uniform(context.scene.frame_start, context.scene.frame_end))
     elif trigger_mode == TriggerMode.RANDOM_GAUSSIAN:
         mean = (context.scene.frame_end - context.scene.frame_start) / 2
         audio_scene_in = floor(gauss(mean, gaussian_stddev))
@@ -127,11 +143,6 @@ def constrain_speaker_to_mesh(speaker_obj, mesh):
     location_loc.target = mesh
     location_loc.target = mesh
 
-
-def apply_gain_envelope(speaker_obj, envelope):
-    pass
-
-
 def add_speakers_to_meshes(meshes, context, sound=None,
                            sound_name_prefix=None,
                            sync_peak=False,
@@ -146,7 +157,8 @@ def add_speakers_to_meshes(meshes, context, sound=None,
             print("object is not mesh")
             continue
 
-        envelope = sound_camera_spatial_envelope(context.scene, mesh, considered_range=5.)
+        envelope = sound_camera_spatial_envelope(
+            context.scene, mesh, considered_range=5.)
 
         speaker_obj = next((spk for spk in context.scene.objects
                             if spk.type == 'SPEAKER' and spk.constraints['Copy Location'].target == mesh), None)
@@ -156,7 +168,7 @@ def add_speakers_to_meshes(meshes, context, sound=None,
             speaker_obj = context.selected_objects[0]
 
         constrain_speaker_to_mesh(speaker_obj, mesh)
-        track_speaker_to_camera(speaker_obj, context.scene.camera)
+        track_speaker_to_camera(speaker_obj)
 
         if sound_name_prefix is not None:
             sound = sound_bank.random_sound()
@@ -170,6 +182,4 @@ def add_speakers_to_meshes(meshes, context, sound=None,
                        gaussian_stddev=gaussian_stddev,
                        sound_bank=sound_bank, envelope=envelope)
 
-            apply_gain_envelope(speaker_obj, envelope)
-
         speaker_obj.data.update_tag()

intern/generate_adm.py

@@ -1,38 +1,30 @@
 import bpy
 
-from contextlib import contextmanager
-
-import lxml
-import uuid
-from fractions import Fraction
-import struct
 from os.path import dirname
 
-import numpy
-
-from time import strftime
-
 from typing import List
 
-from ear.fileio.utils import openBw64
-
-from ear.fileio.bw64.chunks import (FormatInfoChunk, ChnaChunk)
-
-from ear.fileio.adm import chna as adm_chna
-from ear.fileio.adm.xml import adm_to_xml
-from ear.fileio.adm.builder import (ADMBuilder)
-from ear.fileio.adm.generate_ids import generate_ids
-
 from .geom_utils import (speaker_active_time_range,
                          speakers_by_min_distance,
                          speakers_by_start_time)
 
-from .object_mix import (ObjectMix, ObjectMixPool, object_mixes_from_source_groups)
+from .object_mix import (ObjectMixPool, object_mixes_from_source_groups)
 
 from .speaker_utils import (all_speakers)
 
 
 def group_speakers(speakers, scene) -> List[List[bpy.types.Object]]:
+    """
+    Accepts a list of speakers and a scene, and returns a list of lists.
+
+    Each list contains a list of speakers which are guaranteed to not have
+    overlapping sounds. Each of the child lists contains a list of speaker
+    objects in ascending order by start time.
+
+    Speakers are allocated to lists on the basis of their minimum distance to
+    the camera according to `speakers_by_min_distance`. Closer sounds will 
+    appear on the earliest list if there is no overlap.
+    """
     def list_can_accept_speaker(speaker_list, speaker_to_test):
         test_range = speaker_active_time_range(speaker_to_test)
 
@@ -47,7 +39,8 @@ def group_speakers(speakers, scene) -> List[List[bpy.types.Object]]:
 
     ret_val = [[]]
     for spk in by_priority:
-        success = False  # flaggy-flag because I can't do a break->continue from the inner
+        success = False  # flaggy-flag because I can't do a break->continue 
+                         # from the inner
         for elem in ret_val:
             if list_can_accept_speaker(elem, spk):
                 elem.append(spk)
@@ -62,112 +55,123 @@ def group_speakers(speakers, scene) -> List[List[bpy.types.Object]]:
     return ret_val
 
 
-def adm_for_object(scene, sound_object: ObjectMix, room_size, adm_builder, object_index):
-    fps = scene.render.fps
-    frame_start = scene.frame_start
-    frame_end = scene.frame_end
-
-    block_formats = sound_object.adm_block_formats(room_size=room_size)
-
-    created = adm_builder.create_item_objects(track_index=object_index,
-                                              name=sound_object.object_name,
-                                              block_formats=block_formats)
-
-    created.audio_object.start = Fraction(frame_start, fps)
-    created.audio_object.duration = Fraction(frame_end - frame_start, fps)
-    created.track_uid.sampleRate = sound_object.sample_rate
-    created.track_uid.bitDepth = sound_object.bits_per_sample
+# def adm_for_object(scene: bpy.types.Scene, sound_object: ObjectMix, room_size,
+#                    adm_builder, object_index):
+#     fps = scene.render.fps
+#     frame_start = scene.frame_start
+#     frame_end = scene.frame_end
+#
+#     # block_formats = sound_object.adm_block_formats(room_size=room_size)
+#
+#     created = adm_builder.create_item_objects(track_index=object_index,
+#                                               name=sound_object.object_name,
+#                                               block_formats=block_formats)
+#
+#     created.audio_object.start = Fraction(frame_start, fps)
+#     created.audio_object.duration = Fraction(frame_end - frame_start, fps)
+#     created.track_uid.sampleRate = sound_object.sample_rate
+#     created.track_uid.bitDepth = sound_object.bits_per_sample
 
 
-def adm_for_scene(scene, sound_objects: List[ObjectMix], room_size):
-    adm_builder = ADMBuilder()
+# def adm_for_scene(scene: bpy.types.Scene, sound_object_mixes: List[ObjectMix],
+#                   room_size):
+#     adm_builder = ADMBuilder()
+#
+#     frame_start = scene.frame_start
+#     frame_end = scene.frame_end
+#     fps = scene.render.fps
+#
+#     adm_builder.create_programme(audioProgrammeName=scene.name,
+#                                  start=Fraction(frame_start, fps),
+#                                  end=Fraction(frame_end, fps))
+#
+#     adm_builder.create_content(audioContentName="Objects")
+#
+#     for object_index, sound_object in enumerate(sound_object_mixes):
+#         adm_for_object(scene, sound_object, room_size,
+#                        adm_builder, object_index)
+#
+#     adm = adm_builder.adm
+#
+#     generate_ids(adm)
+#     chna = ChnaChunk()
+#     adm_chna.populate_chna_chunk(chna, adm)
+#
+#     return adm_to_xml(adm), chna
+#
 
-    frame_start = scene.frame_start
-    frame_end = scene.frame_end
-    fps = scene.render.fps
-
-    adm_builder.create_programme(audioProgrammeName=scene.name,
-                                 start=Fraction(frame_start, fps),
-                                 end=Fraction(frame_end, fps))
-
-    adm_builder.create_content(audioContentName="Objects")
-
-    for object_index, sound_object in enumerate(sound_objects):
-        adm_for_object(scene, sound_object, room_size, adm_builder, object_index)
-
-    adm = adm_builder.adm
-
-    generate_ids(adm)
-    chna = ChnaChunk()
-    adm_chna.populate_chna_chunk(chna, adm)
-
-    return adm_to_xml(adm), chna
+# def bext_data(scene, sample_rate, room_size):
+#     description = "SCENE={};ROOM_SIZE={}\n".format(
+#         scene.name, room_size).encode("ascii")
+#     originator_name = "Blender {}".format(
+#         bpy.app.version_string).encode("ascii")
+#     originator_ref = uuid.uuid1().hex.encode("ascii")
+#     date10 = strftime("%Y-%m-%d").encode("ascii")
+#     time8 = strftime("%H:%M:%S").encode("ascii")
+#     timeref = int(float(scene.frame_start) *
+#                   sample_rate / float(scene.render.fps))
+#     version = 0
+#     umid = b"\0" * 64
+#     pad = b"\0" * 190
+#
+#     data = struct.pack("<256s32s32s10s8sQH64s190s", description,
+#                        originator_name, originator_ref, date10, time8, timeref,
+#                        version, umid, pad)
+#
+#     return data
+#
+#
+# def attach_outfile_metadata(out_format, outfile, room_size, scene,
+#                             sound_objects):
+#     adm, chna = adm_for_scene(scene, sound_objects, room_size=room_size)
+#     outfile.axml = lxml.etree.tostring(adm, pretty_print=True)
+#     outfile.chna = chna
+#     outfile.bext = bext_data(scene, out_format.sampleRate, room_size=room_size)
+#
+#
+# def write_outfile_audio_data(outfile, shortest_file, sound_objects):
+#     READ_BLOCK = 1024
+#     cursor = 0
+#
+#     # Not sure if this is necessary but lets do it
+#     for obj in sound_objects:
+#         obj.mixdown_reader.seek(0)
+#
+#     while True:
+#         remainder = shortest_file - cursor
+#         to_read = min(READ_BLOCK, remainder)
+#         if to_read == 0:
+#             break
+#
+#         buffer = numpy.zeros((to_read, len(sound_objects)))
+#         for i, sound_object in enumerate(sound_objects):
+#             buffer[:, i] = sound_object.mixdown_reader.read(to_read)[:, 0]
+#
+#         outfile.write(buffer)
+#         cursor = cursor + to_read
 
 
-def bext_data(scene, sample_rate, room_size):
-    description = "SCENE={};ROOM_SIZE={}\n".format(scene.name, room_size).encode("ascii")
-    originator_name = "Blender {}".format(bpy.app.version_string).encode("ascii")
-    originator_ref = uuid.uuid1().hex.encode("ascii")
-    date10 = strftime("%Y-%m-%d").encode("ascii")
-    time8 = strftime("%H:%M:%S").encode("ascii")
-    timeref = int(float(scene.frame_start) * sample_rate / float(scene.render.fps))
-    version = 0
-    umid = b"\0" * 64
-    pad = b"\0" * 190
-
-    data = struct.pack("<256s32s32s10s8sQH64s190s", description, originator_name,
-                       originator_ref, date10, time8, timeref, version, umid, pad)
-
-    return data
-
-
-def attach_outfile_metadata(out_format, outfile, room_size, scene, sound_objects):
-    adm, chna = adm_for_scene(scene, sound_objects, room_size=room_size)
-    outfile.axml = lxml.etree.tostring(adm, pretty_print=True)
-    outfile.chna = chna
-    outfile.bext = bext_data(scene, out_format.sampleRate, room_size=room_size)
-
-
-def write_outfile_audio_data(outfile, shortest_file, sound_objects):
-    READ_BLOCK = 1024
-    cursor = 0
-
-    # Not sure if this is necessary but lets do it
-    for obj in sound_objects:
-        obj.mixdown_reader.seek(0)
-
-    while True:
-        remainder = shortest_file - cursor
-        to_read = min(READ_BLOCK, remainder)
-        if to_read == 0:
-            break
-
-        buffer = numpy.zeros((to_read, len(sound_objects)))
-        for i, sound_object in enumerate(sound_objects):
-            buffer[:, i] = sound_object.mixdown_reader.read(to_read)[:, 0]
-
-        outfile.write(buffer)
-        cursor = cursor + to_read
-
-
-def write_muxed_wav(mix_pool: ObjectMixPool, scene, out_format, room_size, outfile, shortest_file):
-    sound_objects = mix_pool.object_mixes
-    attach_outfile_metadata(out_format, outfile, room_size, scene, sound_objects)
-    write_outfile_audio_data(outfile, shortest_file, sound_objects)
-
-
-def mux_adm_from_object_mix_pool(scene, mix_pool: ObjectMixPool, output_filename, room_size=1.):
-    object_count = len(mix_pool.object_mixes)
-    assert object_count > 0
-
-    out_format = FormatInfoChunk(channelCount=object_count,
-                                 sampleRate=scene.render.ffmpeg.audio_mixrate,
-                                 bitsPerSample=24)
-
-    with openBw64(output_filename, 'w', formatInfo=out_format) as outfile:
-        write_muxed_wav(mix_pool, scene, out_format, room_size,
-                        outfile, mix_pool.shortest_file_length)
-
+# def write_muxed_wav(mix_pool: ObjectMixPool, scene, out_format, room_size,
+#                     outfile, shortest_file):
+#     sound_objects = mix_pool.object_mixes
+#     attach_outfile_metadata(out_format, outfile,
+#                             room_size, scene, sound_objects)
+#     write_outfile_audio_data(outfile, shortest_file, sound_objects)
+#
+#
+# def mux_adm_from_object_mix_pool(scene, mix_pool: ObjectMixPool,
+#                                  output_filename, room_size=1.):
+#     object_count = len(mix_pool.object_mixes)
+#     assert object_count > 0
+#
+#     out_format = FormatInfoChunk(channelCount=object_count,
+#                                  sampleRate=scene.render.ffmpeg.audio_mixrate,
+#                                  bitsPerSample=24)
+#
+#     with openBw64(output_filename, 'w', formatInfo=out_format) as outfile:
+#         write_muxed_wav(mix_pool, scene, out_format, room_size,
+#                         outfile, mix_pool.shortest_file_length)
+#
 
 def print_partition_results(object_groups, sound_sources, too_far_speakers):
     print("Will create {} objects for {} sources, ignoring {} sources".format(
@@ -178,11 +182,19 @@ def print_partition_results(object_groups, sound_sources, too_far_speakers):
             print(" - %s" % source.name)
 
 
-def partition_sounds_to_objects(scene, max_objects):
+def partition_sounds_to_objects(scene, max_objects) -> \
+        tuple[list[list[bpy.types.Object]], list[list[bpy.types.Object]]]:
+    """
+    Allocates sounds in the scene into non-overlapping lists of sounds. The
+    second return value is the list of sounds that could not be allocated
+    because the max_objects limit was exceeded.
+
+    Sounds are allocated to lists according to `group_speakers`.
+    """
     sound_sources = all_speakers(scene)
 
     if len(sound_sources) == 0:
-        return []
+        return [], []
 
     object_groups = group_speakers(sound_sources, scene)
     too_far_speakers = []
@@ -196,7 +208,9 @@ def partition_sounds_to_objects(scene, max_objects):
     return object_groups, too_far_speakers
 
 
-def generate_adm(context: bpy.types.Context, filepath: str, room_size: float, max_objects: int):
+def generate_adm(context: bpy.types.Context, filepath: str, 
+                 room_size: float,
+                 max_objects: int) -> set[str]:
     scene = context.scene
 
     object_groups, _ = partition_sounds_to_objects(scene, max_objects)
@@ -209,10 +223,8 @@ def generate_adm(context: bpy.types.Context, filepath: str, room_size: float, ma
                                                  base_dir=dirname(filepath))
 
     with ObjectMixPool(object_mixes=mix_groups) as pool:
-        mux_adm_from_object_mix_pool(scene, mix_pool=pool,
-                                     output_filename=filepath,
-                                     room_size=room_size)
-        print("Finished muxing ADM")
+        # here is where we place the mix objects into the session
+        pass
 
-    print("generate_adm exiting")
+    # print("generate_adm exiting")
     return {'FINISHED'}

intern/geom_utils.py

@@ -8,17 +8,19 @@ from numpy.linalg import norm
 
 from mathutils import Vector, Quaternion
 
+
 class FrameInterval:
     def __init__(self, start_frame, end_frame):
         self.start_frame = int(start_frame)
         self.end_frame = int(end_frame)
 
-    def overlaps(self, other : 'FrameInterval') -> bool:
+    def overlaps(self, other: 'FrameInterval') -> bool:
         return self.start_frame <= other.start_frame <= self.end_frame or \
             other.start_frame <= self.start_frame <= other.end_frame
 
 
-def compute_relative_vector(camera: bpy.types.Camera, target: bpy.types.Object):
+def compute_relative_vector(camera: bpy.types.Object, 
+                            target: bpy.types.Object): 
     """
     Return a vector from `camera` to `target` in the camera's coordinate space.
 
@@ -33,7 +35,7 @@ def compute_relative_vector(camera: bpy.types.Camera, target: bpy.types.Object):
 
     # The camera's worldvector is norm to the horizon, we want a vector
     # down the barrel.
-    camera_correction = Quaternion( ( sqrt(2.) / 2. , sqrt(2.) / 2. , 0. , 0.) )
+    camera_correction = Quaternion((sqrt(2.) / 2., sqrt(2.) / 2., 0., 0.))
     relative_vector.rotate(camera_correction)
 
     return relative_vector
@@ -43,22 +45,24 @@ def room_norm_vector(vec, room_size=1.) -> Vector:
     """
     The Room is tearing me apart, Lisa.
 
-    The room is a cube with the camera at its center. We use a chebyshev normalization
-    to convert a vector in world or camera space into a vector the represents the projection
-    of that vector onto the room's walls. The Room Vector is the immediate the X, Y and Z 
-    coordinate of the corresponding ADM Block Format source object position.
+    The room is a cube with the camera at its center. We use a chebyshev
+    normalization to convert a vector in world or camera space into a vector
+    the represents the projection of that vector onto the room's walls. The
+    Room Vector is the immediate the X, Y and Z coordinate of the corresponding
+    ADM Block Format source object position.
 
-    The Pro Tools/Dolby Atmos workflow I am targeting uses "Room Centric" panner coordinates
-    ("cartesian allocentric coordinates" in ADM speak) and this process seems to yield good
-    results.
-    
-    I also experimented with using normalized camera frame coordinates from the 
-    bpy_extras.object_utils.world_to_camera_view method and this gives very good results as
-    long as the object is on-screen; coordinates for objects off the screen are unusable.
-    
-    In the future it would be worth exploring wether there's a way to produce ADM 
-    coordinates that are "Screen-accurate" while the object is on-screen, but still gives
-    sensible results when the object is off-screen as well.
+    The Pro Tools/Dolby Atmos workflow I am targeting uses "Room Centric"
+    panner coordinates ("cartesian allocentric coordinates" in ADM speak) and
+    this process seems to yield good results.
+
+    I also experimented with using normalized camera frame coordinates from the
+    bpy_extras.object_utils.world_to_camera_view method and this gives very
+    good results as long as the object is on-screen; coordinates for objects
+    off the screen are unusable.
+
+    In the future it would be worth exploring wether there's a way to produce
+    ADM coordinates that are "Screen-accurate" while the object is on-screen,
+    but still gives sensible results when the object is off-screen as well.
     """
     chebyshev = norm(vec, ord=numpy.inf)
     if chebyshev < room_size:
@@ -67,19 +71,20 @@ def room_norm_vector(vec, room_size=1.) -> Vector:
         return vec / chebyshev
 
 
-def closest_approach_to_camera(scene, speaker_object) -> (float, int):
+def closest_approach_to_camera(scene, speaker_object) -> tuple[float, int]:
     """
-    The distance and frame number of `speaker_object`s closest point to
-    the scene's camera.
-    
+    The distance and frame number of `speaker_object`s closest point to the
+    scene's camera.
+
     (Works for any object, not just speakers.)
     """
     max_dist = sys.float_info.max
     at_time = scene.frame_start
     for frame in range(scene.frame_start, scene.frame_end + 1):
         scene.frame_set(frame)
-        rel = speaker_object.matrix_world.to_translation() - scene.camera.matrix_world.to_translation()
-        dist = norm(rel)
+        rel = speaker_object.matrix_world.to_translation() - \
+            scene.camera.matrix_world.to_translation()
+        dist = float(norm(rel))
 
         if dist < max_dist:
             max_dist = dist
@@ -105,6 +110,10 @@ def speaker_active_time_range(speaker) -> FrameInterval:
 
 
 def speakers_by_min_distance(scene, speakers):
+    """
+    Sorts a list of speaker objects in ascending order by their closest
+    approach to the camera. Objects that approach closest are sorted highest.
+    """
     def min_distance(speaker):
         return closest_approach_to_camera(scene, speaker)[0]
 
@@ -112,4 +121,5 @@ def speakers_by_min_distance(scene, speakers):
 
 
 def speakers_by_start_time(speaker_objs):
-    return sorted(speaker_objs, key=(lambda spk: speaker_active_time_range(spk).start_frame))
+    return sorted(speaker_objs, 
+                  key=(lambda spk: speaker_active_time_range(spk).start_frame))

intern/object_mix.py

@@ -1,18 +1,15 @@
 import os
 import bpy
 from contextlib import contextmanager
-from fractions import Fraction
 from typing import List
 
-from ear.fileio.adm.elements import ObjectCartesianPosition, JumpPosition, AudioBlockFormatObjects
-from ear.fileio.bw64 import Bw64Reader
+import wave
 
-from .geom_utils import speaker_active_time_range, compute_relative_vector, room_norm_vector
 from .speaker_utils import solo_speakers, unmute_all_speakers
 
 
 @contextmanager
-def adm_object_rendering_context(scene: bpy.types.Scene):
+def object_rendering_context(scene: bpy.types.Scene):
     old_ff = scene.render.image_settings.file_format
     old_codec = scene.render.ffmpeg.audio_codec
     old_chans = scene.render.ffmpeg.audio_channels
@@ -31,14 +28,14 @@ def adm_object_rendering_context(scene: bpy.types.Scene):
 
 
 class ObjectMix:
-    def __init__(self, sources: List[bpy.types.Speaker],
+    def __init__(self, sources: List[bpy.types.Object],
                  scene: bpy.types.Scene, base_dir: str):
         self.sources = sources
         self.intermediate_filename = None
         self.base_dir = base_dir
         self.scene = scene
-        self._mixdown_file_handle = None
-        self._mixdown_reader = None
+        # self._mixdown_file_handle = None
+        # self._mixdown_reader = None
 
     @property
     def frame_start(self):
@@ -48,33 +45,27 @@ class ObjectMix:
     def frame_end(self):
         return self.scene.frame_end
 
-    @property
-    def sample_rate(self):
-        return self.mixdown_reader.sampleRate
+    @property 
+    def sample_rate(self) -> int:
+        with wave.open(self.mixdown_filename, "rb") as f:
+            return f.getframerate()
 
     @property
-    def bits_per_sample(self):
-        return self.mixdown_reader.bitdepth
+    def bits_per_sample(self) -> int:
+        with wave.open(self.mixdown_filename, "rb") as f:
+            return f.getsampwidth() * 8
+
+    @property 
+    def frames_length(self) -> int:
+        with wave.open(self.mixdown_filename, "rb") as f:
+            return f.getnframes()
 
     @property
-    def mixdown_reader(self) -> Bw64Reader:
-        if self._mixdown_reader is None:
-            self._mixdown_reader = Bw64Reader(self.mixdown_file_handle)
-
-        return self._mixdown_reader
-
-    @property
-    def mixdown_file_handle(self):
-        if self._mixdown_file_handle is None:
-            self._mixdown_file_handle = open(self.mixdown_filename, 'rb')
-
-        return self._mixdown_file_handle
-
-    @property
-    def mixdown_filename(self):
+    def mixdown_filename(self) -> str:
         if self.intermediate_filename is None:
             self.mixdown()
-
+        
+        assert self.intermediate_filename
         return self.intermediate_filename
 
     @property
@@ -82,49 +73,23 @@ class ObjectMix:
         return self.sources[0].name
 
     def mixdown(self):
-        with adm_object_rendering_context(self.scene) as scene:
+        with object_rendering_context(self.scene) as scene:
             solo_speakers(scene, self.sources)
 
             scene_name = bpy.path.clean_name(scene.name)
             speaker_name = bpy.path.clean_name(self.object_name)
 
-            self.intermediate_filename = os.path.join(self.base_dir, "%s_%s.wav" % (scene_name, speaker_name))
+            self.intermediate_filename = os.path.join(
+                self.base_dir, "%s_%s.wav" % (scene_name, speaker_name))
 
             bpy.ops.sound.mixdown(filepath=self.intermediate_filename,
-                                  container='WAV', codec='PCM', format='S24')
+                                  container='WAV', codec='PCM', format='F32')
 
-            print("Created mixdown named {}".format(self.intermediate_filename))
+            print("Created mixdown named {}"
+                  .format(self.intermediate_filename))
 
             unmute_all_speakers(scene)
 
-    def adm_block_formats(self, room_size=1.):
-        fps = self.scene.render.fps
-        block_formats = []
-
-        for speaker_obj in self.sources:
-            speaker_interval = speaker_active_time_range(speaker_obj)
-            for frame in range(speaker_interval.start_frame, speaker_interval.end_frame + 1):
-                self.scene.frame_set(frame)
-                relative_vector = compute_relative_vector(camera=self.scene.camera, target=speaker_obj)
-
-                norm_vec = room_norm_vector(relative_vector, room_size=room_size)
-
-                pos = ObjectCartesianPosition(X=norm_vec.x, Y=norm_vec.y, Z=norm_vec.z)
-
-                if len(block_formats) == 0 or pos != block_formats[-1].position:
-                    jp = JumpPosition(flag=True, interpolationLength=Fraction(1, fps * 2))
-                    block = AudioBlockFormatObjects(position=pos,
-                                                    rtime=Fraction(frame, fps),
-                                                    duration=Fraction(1, fps),
-                                                    cartesian=True,
-                                                    jumpPosition=jp)
-
-                    block_formats.append(block)
-                else:
-                    block_formats[-1].duration = block_formats[-1].duration + Fraction(1, fps)
-
-        return block_formats
-
     def rm_mixdown(self):
         if self._mixdown_reader is not None:
             self._mixdown_reader = None
@@ -146,17 +111,20 @@ class ObjectMixPool:
     def __enter__(self):
         return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb):
+    def __exit__(self, _exc_type, _exc_val, _exc_tb):
         for mix in self.object_mixes:
             mix.rm_mixdown()
 
     @property
     def shortest_file_length(self):
-        lengths = map(lambda f: len(f.mixdown_reader), self.object_mixes)
+        lengths = map(lambda f: f.frames_length, self.object_mixes)
         return min(lengths)
 
 
-def object_mixes_from_source_groups(groups: List[List[bpy.types.Speaker]], scene, base_dir):
+def object_mixes_from_source_groups(
+        groups: List[List[bpy.types.Object]],                            
+        scene: bpy.types.Scene, base_dir: str) -> list[ObjectMix]:
+    
     mixes = []
     for group in groups:
         mixes.append(ObjectMix(sources=group, scene=scene, base_dir=base_dir))

intern/soundbank.py

@@ -1,48 +0,0 @@
-import bpy
-
-import numpy
-
-from typing import List
-from random import choice
-from aud import Sound
-
-class SoundBank:
-    def __init__(self, prefix):
-        self.prefix = prefix
-        self.cached_info = {}
-
-    def sounds(self) -> List[Sound]:
-        return [sound for sound in bpy.data.sounds if sound.name.startswith(self.prefix)] 
-
-    def random_sound(self) -> Sound:
-        if len(self.sounds()) == 0:
-            return None
-        else:
-            return choice(self.sounds())
-
-    def get_audiofile_info(self, sound, fps) -> (int, int):
-        """
-        Returns frame of max_peak and duration in frames
-        """
-        
-        if sound.filepath in self.cached_info.keys():
-            return self.cached_info[sound.filepath]
-        else:
-            if sound.filepath.startswith("//"):
-                path = bpy.path.abspath(sound.filepath)
-            else:
-                path = sound.filepath
-
-            aud_sound = Sound(path)
-            samples = aud_sound.data()
-            sample_rate = aud_sound.specs[0]
-            index = numpy.where(samples == numpy.amax(samples))[0][0]
-            max_peak_frame = (index * fps / sample_rate)
-
-            sample_count = aud_sound.length
-            frame_length = sample_count * fps / sample_rate
-
-            retvalue = (max_peak_frame , frame_length)
-            self.cached_info[sound.filepath] = retvalue
-
-            return retvalue

intern/speaker_utils.py

@@ -1,9 +1,16 @@
-def all_speakers(scene):
+import bpy 
+
+def all_speakers(scene: bpy.types.Scene) -> list[bpy.types.Object]:
     return [obj for obj in scene.objects if obj.type == 'SPEAKER']
 
 
-def solo_speakers(scene, solo_group):
+def solo_speakers(scene: bpy.types.Scene, solo_group: list[bpy.types.Object]):
+    """
+    Mutes all Objects not in `solo_group` and ensures all objects in this group
+    are not muted.
+    """
     for speaker in all_speakers(scene):
+        assert type(speaker.data) is bpy.types.Speaker
         if speaker in solo_group:
             speaker.data.muted = False
         else:
@@ -13,6 +20,10 @@ def solo_speakers(scene, solo_group):
 
 
 def unmute_all_speakers(scene):
+    """
+    Unmutes all speakers.
+    """
     for speaker in all_speakers(scene):
+        assert type(speaker.data) is bpy.types.Speaker
         speaker.data.muted = False
         speaker.data.update_tag()

operator_adm_export.py

@@ -1,33 +1,36 @@
 from bpy_extras.io_utils import ExportHelper
-from bpy.props import StringProperty, BoolProperty, EnumProperty, FloatProperty, IntProperty
+from bpy.props import StringProperty, BoolProperty, FloatProperty, IntProperty
 from bpy.types import Operator
 
 from .intern.generate_adm import generate_adm
 
-class ADMWaveExport(Operator, ExportHelper):
-    """Export a Broadcast-WAV audio file with each speaker encoded as an ADM object"""
-    bl_idname = "export.adm_wave_file"  # important since its how bpy.ops.import_test.some_data is constructed
-    bl_label = "Export ADM Wave File"
 
-    # ExportHelper mixin class uses this
+class ADMWaveExport(Operator, ExportHelper):
+    """
+    Export a Broadcast-WAV audio file with each speaker encoded as an ADM
+    object
+    """
+    bl_idname = "export.adm_wave_file"  # important since its how
+    bl_label = "Export ADM Wave File"
+    filepath: str
     filename_ext = ".wav"
 
-    filter_glob: StringProperty(
+    filter_glob = StringProperty(
         default="*.wav",
         options={'HIDDEN'},
         maxlen=255,  # Max internal buffer length, longer would be clamped.
     )
-    
-    room_size: FloatProperty(
+
+    room_size = FloatProperty(
         default=1.0,
         name="Room Size",
         description="Distance from the lens to the front room boundary",
         min=0.001,
-        step=1.,
+        step=1,
         unit='LENGTH'
     )
 
-    max_objects: IntProperty(
+    max_objects = IntProperty(
         name="Max Objects",
         description="Maximum number of object tracks to create",
         default=24,
@@ -35,13 +38,14 @@ class ADMWaveExport(Operator, ExportHelper):
         max=118
     )
 
-    create_bed: BoolProperty(
+    create_bed = BoolProperty(
         name="Create 7.1 Bed",
-        description="Create a bed for all sounds not included on object tracks",
+        description="Create a bed for all sounds not included on object "
+        "tracks",
         default=False,
         options={'HIDDEN'}
     )
 
-    def execute(self, context):
-        return generate_adm(context, self.filepath, self.room_size, self.max_objects)
-
+    def execute(self, context) -> set:
+        return generate_adm(context, self.filepath, self.room_size,
+                            self.max_objects)

operator_wav_import.py

@@ -1,58 +0,0 @@
-import bpy
-import os
-
-def import_wav_files(filepath, pack, dir, fake):
-    
-    def import_one(fp):
-        sound = bpy.data.sounds.load(fp, check_existing=False)
-        if pack:
-            sound.pack()
-            
-        if fake:
-            sound.use_fake_user = True
-            
-    if dir:
-        the_dir = os.path.dirname(filepath)
-        for child in os.listdir(the_dir):
-            if child.endswith(".wav"):
-                import_one(os.path.join(the_dir, child))
-                
-    else:
-        import_one(filepath)
-        
-    return {'FINISHED'}
-
-
-from bpy_extras.io_utils import ImportHelper
-from bpy.props import StringProperty, BoolProperty, EnumProperty
-from bpy.types import Operator
-
-
-class ImportWav(Operator, ImportHelper):
-    """Import WAV audio files"""
-    bl_idname = "import_test.wav_file_batch" 
-    bl_label = "Import WAV Files"
-
-    filename_ext = ".wav"
-
-    filter_glob: StringProperty(
-        default="*.wav",
-        options={'HIDDEN'},
-        maxlen=255,  # Max internal buffer length, longer would be clamped.
-    )
-    
-    fake: BoolProperty(
-        name="Add Fake User",
-        description="Add the Fake User to each of the sound files",
-        default=True,
-    )
-    
-    all_in_directory: BoolProperty(
-        name="All Files in Folder",
-        description="Import every WAV file found in the folder as the selected file",
-        default=False,
-    )
-
-    def execute(self, _):
-        return import_wav_files(filepath=self.filepath, pack=False, dir=self.all_in_directory, fake=self.fake)
-

requirements_dev.txt

@@ -0,0 +1,37 @@
+asttokens==3.0.0
+attrs==21.4.0
+certifi==2025.10.5
+charset-normalizer==3.4.4
+cython==3.2.0
+decorator==5.2.1
+executing==2.2.1
+fake-bpy-module-4-3==20250130
+idna==3.11
+ipython==9.7.0
+ipython-pygments-lexers==1.1.1
+jedi==0.19.2
+mathutils==3.3.0
+matplotlib-inline==0.2.1
+multipledispatch==0.6.0
+mypy==1.18.2
+mypy-extensions==1.1.0
+numpy==1.26.4
+parso==0.8.5
+pathspec==0.12.1
+pexpect==4.9.0
+pip==25.0.1
+prompt-toolkit==3.0.52
+ptyprocess==0.7.0
+pure-eval==0.2.3
+pygments==2.19.2
+requests==2.32.5
+ruamel-yaml==0.18.16
+ruamel-yaml-clib==0.2.14
+setuptools==78.1.0
+six==1.17.0
+stack-data==0.6.3
+traitlets==5.14.3
+typing-extensions==4.15.0
+urllib3==2.5.0
+wcwidth==0.2.14
+zstandard==0.25.0