Coder Social home page Coder Social logo

Improve the introduction about iamf HOT 4 CLOSED

aomediacodec avatar aomediacodec commented on August 11, 2024
Improve the introduction

from iamf.

Comments (4)

sunghee-hwang avatar sunghee-hwang commented on August 11, 2024

It would be better to take this action after most of the spec texts are cleared.

from iamf.

tdaede avatar tdaede commented on August 11, 2024

I do want to leave this open just because although most of this has been fixed by #95, I do think the introduction is a bit abrupt now and could use maybe one more pass.

from iamf.

cconcolato avatar cconcolato commented on August 11, 2024

Here are some high level suggestions to improve the introduction:

My main concern is that the introduction explains the "how" (model, syntax), without giving an indication of the "why". It should contain examples of how to instantiate the model for typical IAMF use cases, from the most simple use case (1 Mix Presentation, 1 Audio Element, 1 or N substreams to achieve speaker layouts that are badly addressed today) to most complex examples.

The specification should start with the introduction rather than with the conventions. The reader is more interested in understanding what the spec is about rather than what conventions were used. I would move the convention section to the end of the spec, maybe with a sentence in the current section 3 saying that conventions are described in section X, providing a hyperlink to it.

Some more detailed comments below:
Before Section 2.1

  • "The immersive audio means" This seems to be missing the word "term": -> "The term immersive audio means"

  • The term "3D audio signals" should be defined. Also is it plural or singular? A sentence below uses "For a given input 3D audio".

  • "based on coded audio substreams" -> "based on coded audio bitstreams, called 'substreams'"

  • Clarify in the paragraph above Figure 1 if the 2 sets of "physical loudspeakers" have the same configuration. Maybe update the figure to say "... loudspeakers (configuration 1)" and ".. loudspeaker (configuration 2)?

  • The terms in the bulleted list below Figure 2 should define the terms or link to where these terms are defined: "Pre-Processor", "Pre-Processed Audio", "Codec Agnostic Metadata", "Audio Codec Enc", "Codec-Dependent Bitstream" "coded substreams", "Bitstream Packager", "IA sequence", "File Packager", "IAMF File" "File Parser", "Bitstream Parser", "Audio Codec Dec", "Post-Processor", "Pre-Processed Audio"

  • Figure 1 is really about illustrating the model which is defined in section 2.1. Consider moving Figure 1 to section 2.1.

  • Section 2.1

  • "The IA sequence is a bitstream" -> "An IA sequence is a bitstream".

  • "An IA sequence is a bitstream": it is confusing. Is an "IA Sequence" a concrete object or an abstraction/logical concept.

  • "dynamic streaming" is confusing. What is "dynamic"? Delete "dynamic" or define it.

  • "The bitstream comprises a number of coded audio substreams": The use of the term "bitstream" is confusing. Does it refer to the "Codec-Dependent Bitstream"?

  • "The bitstream format itself is codec-agnostic": This is confusing as usual a "bitstream" as a concrete syntax and is not codec-agnostic.

  • "Audio substream is the actual audio signal" -> "An audio substream is an actual audio signal"

  • "Audio element is the 3D representation of the audio signals": It is confusing because the "IA Sequence" is already "the combination of 3D audio signals". Maybe use "signal" singular?

  • "Parameters" is a very generic term. Could you prefix it? Maybe "IA Parameter"?

Section 2.2.1

  • The term OBU is used without being defined or linked.
  • It is not clear why Section 2 starts talking about OBUs. I suggest adding before section 2.2.1 (or in the first paragraphs of section 2) a paragraph explaining that an "IA Sequence" refers to an abstract term within a hierarchical model, while OBU is the concrete, physical unit use to represent the objects in the model.
  • The term Descriptor is not defined, nor introduced. It misses a sentence saying that there are 2 types of OBUs: Descriptor OBUs that do not contain audio signal and Data OBU that contain coded audio signals/
  • Consider adding a figure with a sequence of OBUs, starting with Magic Code OBU, ...

Section 2.2.2

from iamf.

sunghee-hwang avatar sunghee-hwang commented on August 11, 2024

@cconcolato, thank you for your wonderful suggestions to improve its readability.
Let me take this action after resolving technical issues which are related to Ref. S/W implementation. Anyway, the shape would be like this.

  • Section 1 Introduction: IAMF use cases from typical ones to complex ones
  • Section 1.1 IA sequence components: Figure 1, definitions for IA sequence and components. (Abstract-wise)
    . I think that "IA sequence" can be used in our spec as both concrete object and abstract/logical concept.
  • Section 1.2 Use of OBU syntax (Concrete-wise)

from iamf.

Related Issues (20)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.