Is It Possible to Import Multiple Streams as a Single Clip That Expands into Stacked Layers in PR

[powerful_think1966]

Hello Adobe Community,

I am currently developing an Importer using the Premiere Pro SDK.

The goal of the importer I am working on is to function purely as a dummy clip.
When a file is dropped onto the timeline from a CEP panel, the Project panel, or Windows Explorer, it should only store the start time and duration and then be removed.
In other words, the clip itself does not represent actual media.

The behavior of the Premiere Composer importer plugin matches exactly what I am aiming to achieve.

At the moment, I have successfully implemented importing as a single clip, and this works as expected.
However, I have been unable to implement the behavior where multiple streams are recognized as a single clip, but when dropped onto the timeline, they are expanded into a stacked, layered structure.

To be honest, I am not even certain whether this kind of behavior is achievable at the Importer API level.

I have already spent a significant amount of time working on importer development, but unfortunately, I have made no real progress on this issue.

If there are any experienced or knowledgeable developers here, I would sincerely appreciate your guidance on how this might be solved.

Below is a summary of what I have observed so far.

When GetInfo8 returns imIterateStreams and I advertise the existence of multiple streams to the host,
Premiere places them into the Bin as a single clip.

When I assign a streamName to each stream,
Premiere places them into the Bin as two separate streams.

I would like to try labeling streams using imQueryStreamLabel,
but this selector has never been called, and I have no understanding of under what conditions it is triggered.
It has never been invoked so far.

When I set streamsAsComp to true,
Premiere loads a sequence and one clip with two streams into the Bin,
and within the sequence, the streams are expanded and stacked.

The behavior also changes depending on whether the streams share the same metadata or not.

This is the closest I have come to a positive result, since the streams are at least stacked inside a sequence.
However, because they are contained within a sequence in the Bin,
the file cannot be dropped directly onto the timeline, which defeats the purpose.

I have tried many other approaches as well,
but I have not been able to achieve the desired result.

No matter what I do,
I cannot seem to implement an importer that is recognized as a single clip
and expands into stacked layers when dropped onto the timeline.

Is there any known solution, workaround, or even a hint
that could point me in the right direction?

Was this functionality implemented through an unofficial approach,
or possibly reverse engineering?

I am truly desperate for help.
This feature is something I really need to implement.

Thank you very much for your time and consideration.

[Warren Heaton]

Hi, @powerful_think1966:

Could you mock-up a screen shot of what this might look like?

"Streams" and "Clips" are the same thing.  So, to have multiple streams as single clip is a little confusing.  

[powerful_think1966]

In the first screenshot, the .mhbricks clip is imported as a single item in the Project panel.
However, when selected, the timeline track indicators show V1, V2, A1, and A2 as active, which means the clip internally contains multiple streams even though it appears as one clip.

In the second screenshot, when I start dragging this single clip onto the timeline, Premiere automatically expands it based on the internal stream layout.
The clip previews exactly as V1 / V2 for video layers and A1 / A2 for audio layers, and once dropped, it correctly places each stream as stacked tracks on the timeline.

In my current implementation, a file can only be imported as a single clip when it advertises one video stream and multiple audio streams.

However, as soon as I advertise more than one video stream (e.g., V1 + V2), Premiere seems to fall back to a different behavior and loads the content into the Bin folder as separate items, instead of keeping it as one unified clip.

My goal is to achieve the same behavior as .mhbricks, where:

Multiple video streams (V1, V2, V3, …) and

Multiple audio streams (A1, A2, …)

can all be recognized as internal layered streams, while still importing as a single clip in the Project panel, and expanding into stacked tracks only when dropped on the timeline.

[Bruce Bullis · Accepted solution]

>The behavior of the Premiere Composer importer plugin matches exactly what I am aiming to achieve.

While I cannot provide any details specific to Mister Horse's implementation, I can confirm that they're using public APIs to accomplish that behavior. 

What I think is missing from your approach as described [above], is establishing a communications channel "behind PPro's back", so that your .mhbricks Importer plugin can drive your UXP plugin to import and arrange assets, to match the info in the .mhbricks file. 

[powerful_think1966]

Hello, thank you for your response.

I would like to ask for some clarification on the following statement:

>The behavior of the Premiere Composer importer plugin matches exactly what I am aiming to achieve.

While I cannot provide any details specific to Mister Horse's implementation, I can confirm that they're using public APIs to accomplish that behavior. 

What I think is missing from your approach as described [above], is establishing a communications channel "behind PPro's back", so that your .mhbricks Importer plugin can drive your UXP plugin to import and arrange assets, to match the info in the .mhbricks file. 

By @Bruce Bullis

Could you please explain in more detail what “establishing a communications channel behind PPro’s back” means in this context?

I understand this may involve broader domain knowledge, but even a high-level explanation of the overall idea or direction would be extremely helpful. I will try to research the details further on my own.

1. Multi-stream single-clip loading (video N, audio N)

Currently, in **GetInfo8**, I am using **imIterateStreams** to notify the host about available streams and to populate **vidInfo** and **audInfo** accordingly.

Beyond this step, what additional implementation is required to allow **multiple video streams and multiple audio streams to be loaded as a single clip** in Premiere Pro?

Specifically:

* Is there additional communication or state management expected outside of the standard importer callbacks?

* Are there assumptions in Premiere Pro about how streams are internally grouped that the importer must explicitly support?

2. imQueryStreamLabel — when is it called?

I would also like to ask about imQueryStreamLabel

* Under what conditions does Premiere Pro call imQueryStreamLabel?

* In my implementation, this command has never been called, even once.

* It *seems* like this command should be relevant (or even required) when handling multiple video streams as a single clip, but I cannot determine why it is never triggered.

Is it possible that:

* Certain prerequisites must be met before Premiere Pro calls `imQueryStreamLabel`?

* Or that this command is only used in very specific workflows or UI contexts?

Unfortunately, I have not been able to find any sample code or concrete examples demonstrating real usage of `imQueryStreamLabel`.

If there is any documentation, sample, or even a conceptual explanation of how and when it is expected to be used, I would greatly appreciate it.

3. Meaning of “behind PPro’s back”

Finally, going back to the phrase “behind PPro’s back:

Could you explain what this implies architecturally?

For example:

* Does this mean maintaining an out-of-band communication mechanism not directly driven by Premiere Pro callbacks?

* Or managing stream selection, synchronization, or metadata independently of PPro’s internal assumptions?

Even a rough explanation of the intent behind this phrase would be very helpful as a hint toward the correct design approach.

Thank you very much for your time and insights.

Any guidance, even at a conceptual level, would be sincerely appreciated.

Best regards,

—and Happy New Year

[Bruce Bullis]

>...going back to the phrase “behind PPro’s back: Could you explain what this implies architecturally?

Yes! Create some sort of communication between your Importer (which gets to parse the actual imported file), and a panel (either CEP or UXP), which can create and instantiate project items, sequences and track items, and control...basically everything except providing PPro with video and audio data, which is what your Importer does. 🙂

[powerful_think1966]

😢

I’m still having a hard time understanding what you mean.

Do you mean that I should not try to create a “complete multistream single clip” using only an Importer?

The Mister Horse importer is able to load a single clip containing multiple video and multiple audio streams using only a single importer .prm, without any CEP or UXP panel running at all.

So I’m sorry, but I still don’t clearly understand what you are suggesting.

I also don’t really understand what you mean by “establishing a communication channel between the Importer and a CEP/UXP panel.”

In the end, CEP is just ExtendScript plus ExternalObject. What exactly can it do beyond that?

Even when handling drag events using event.dataTransfer.setData,

if multiple data files are involved, Premiere always arranges them horizontally, not as a stacked structure.

This is actually the part I’ve been struggling with for a very long time and still haven’t been able to resolve.

What I want is very clear:

I want to report multiple video streams and multiple audio streams to the host,

and have the host clearly interpret and load them as a single multistream clip.

Specifically, I want a single clip (multistream: video n, audio n) such that:

When the clip is selected in the Project Panel,

the blue track targeting indicators light up on V1, V2, A1, A2, etc.

When dragging the clip to the timeline,

the stacked multistream structure is visible during the drag

After dropping, the clip is inserted exactly in that stacked form

This is exactly the behavior that mhbricks demonstrates.

Since this process seems to be entirely handled between the Importer and the host’s interpretation of that importer,

what else can I realistically do here?

That’s why I don’t understand what “communication between the Importer and a CEP panel” is supposed to mean in this context.

Could you please provide some additional clarification?

I genuinely don’t understand how the Importer and a CEP panel are related in this scenario,

or what architectural role the panel is supposed to play according to your explanation.

I would really appreciate a more detailed explanation.

[Bruce Bullis]

>Do you mean that I should not try to create a “complete multistream single clip” using only an Importer?

I think so, yes. 

What is actually contained in the file you're importing? Is it strictly media essence data? If not, then anything other than media essence data will need to be brought into the project NOT by the Importer, but by a CEP or UXP panel.

> The Mister Horse importer is able to load a single clip containing multiple video and multiple audio streams

>  using only a single importer .prm, without any CEP or UXP panel running at all.

Again, I can't discuss any specifics of a 3rd party's implementation, but I think you'll find that they do install and use an invisible CEP panel. 

>and have the host clearly interpret and load them as a single multistream clip.

In PPro, there is no such thing as a "clip"; there are only projectItems, and trackItems. 🙂

An Importer can report that it can provide multiple video streams, during imGetInfo8; search the docs for 

"imIterateStreams". However, each such video stream will show up as a distinct projectItem, and not a "single multistream clip". This differs from PPro's audio stream behavior; any projectItem can have multiple audio streams. 

[powerful_think1966]

Hello, thank you for your response.

When you say this should be handled via CEP/UXP rather than an importer, do you mean the following?

- Drop something as a single Project Item (or Track Item) using `event.dataTransfer.setData()`,
and then post-process it via CEP + ExtendScript to load multiple files as a layered (stacked) structure.

Or is there another approach that I am missing?

If you mean “drop one item into the timeline and then build the layered structure via CEP + ExtendScript post-processing,”

that is not my goal.

My goal is for the host to recognize, at the importer level, a single Project Item that contains true multistream
(Video N streams, Audio N streams) like V1, V2, A1, A2 (i.e., multiple video and audio streams within one Project Item).

However, the SDK documentation is very confusing to me.

In some places, it sounds like multiple video streams and multiple audio streams are supported,
but in other places it feels like only multi-audio streams are supported.

I also cannot find a clear Q&A about this on the Adobe community.
If you can provide a definitive answer here, I believe other developers will also benefit from it.

I am very close to giving up on developing a multistream importer.

However, before I stop, the last feature I want to test is `imQueryStreamLabel`:

https://ppro-plugins.docsforadobe.dev/importers/getting-started/#stereoscopic-video

--------------------------------
About imQueryStreamLabel
--------------------------------

According to the SDK documentation:

"It is not desirable to have two project items.
To merge them, the importer needs to label the streams.
If there are multiple labeled video streams, it will appear as a single project item,
and all views on that item will show the first stream.
For this there is a new selector: `imQueryStreamLabel`."

This seems to be the only remaining way to make multiple video streams appear as a single Project Item.

However, in my importer:

- `imQueryStreamLabel` is never called.
- This is true even when multiple video streams are reported.

I cannot find concrete information about:

- When the host decides to call `imQueryStreamLabel`
- What exact conditions must be satisfied
- Or any sample code that demonstrates this behavior

--------------------------------
Final Questions
--------------------------------

01. Under what exact conditions does the host call `imQueryStreamLabel`?

02. Is there any sample code, or at least a minimal working example,
where multiple video streams are merged into a single Project Item?

03. According to the official Premiere Pro SDK API definition,
does "multistream" only mean one video stream with multiple audio streams (video 1 / audio N)?

04. According to the official Premiere Pro SDK API definition,
is it possible to implement true multistream as a single Project Item
with video N streams and audio N streams?

I have invested a significant amount of time into this work and I am mentally exhausted.

Before giving up on multistream importer development, I would like to test this last possibility: `imQueryStreamLabel`.

Even if `imQueryStreamLabel` is unrelated to multistream support,
I still want to confirm it before I completely stop this work.

I would greatly appreciate a detailed explanation of `imQueryStreamLabel`.

Thank you very much for your time and help.

I may have to give up soon, but I would really appreciate your clarification.

[Bruce Bullis]

>When you say this should be handled via CEP/UXP rather than an importer, do you mean the following?

No, I don't mean anything about drag-n-drop.

The distinction I was trying to make:

Importers are designed to import video and audio essence data (pixels and audio samples) from media files, into PPro, as project items. 
CEP extensions and UXP "plugins" (that's marketing; they're still extensions) are designed to manipulate all aspects of project items.

Important distinction: Extensions never, ever get access to essence data, nor are they asked to provide essence data. 

Example: Let's imagine .xyz files,  which contain video frames and audio samples. To support the .xyz file format in PPro, you would write an Importer. 

If, you instead wanted to import files of any type into the project, arrange them in bins, create sequences, and insert media into sequences, you would write an extension.

Make more sense? 

> 01. Under what exact conditions does the host call `imQueryStreamLabel`?

This is used by stereoscopic importers to specify which stream IDs represent the left and right eyes.

> 02 Is there any sample code, or at least a minimal working example,
where multiple video streams are merged into a single Project Item?

No. 

> 03. According to the official Premiere Pro SDK API definition,
does "multistream" only mean one video stream with multiple audio streams (video 1 / audio N)?

Yes.

> 04. According to the official Premiere Pro SDK API definition,
is it possible to implement true multistream as a single Project Item
with video N streams and audio N streams?

No.

[powerful_think1966]

Thank you for your previous response.

However, it appears your answer was based on a scenario where video stream labels are not being provided via imQueryStreamLabel.

Stereoscopic Video
https://ppro-plugins.docsforadobe.dev/importers/getting-started/?h=imquerystreamlabel#stereoscopic-v...

The SDK Guide, in the Stereoscopic Video section, states the following:

"First, an importer must advertise multiple video streams.... Now, obviously, it is not desirable to have two project items. In order to get them merged, an importer needs to label the streams (the logic here is pretty simple, if there are multiple labeled video streams, it will appear as a single project item, and all views on that item will show the first stream). For this there is a new selector: imQueryStreamLabel. The struct passed to the importer has its privateData, prefs data, and the stream index, and the label needs to be passed back in a PrSDKString. If you're not familiar with PrSDKStringSuite, it's fairly obvious how to use. In this case you'll be allocating a string, passing either UTF-8 data, or UTF-16 data."

This clearly indicates that imQueryStreamLabel is the core mechanism for merging multiple video streams into a single Project Item. I would like to explore this functionality further, but in my current implementation, I have not been able to observe the host calling this selector at all.

The guide also mentions:

"However, the entire StreamLabel mechanism is intentionally left quite general."

In particular, the guide indicates that the stream labeling mechanism can be used for general purposes. If the guide’s explanation is accurate, providing stream labels via imQueryStreamLabel should allow multiple video streams to be imported as a single Project Item.

My current goal is to write code that clearly induces the host to call imQueryStreamLabel.

[Final Question]

What is the exact code-level condition required for the host to trigger this selector? Specifically, what combination of flags (e.g., ivProjectionType, etc.) or struct field values must be set during the imGetInfo8 stage to initiate this call? I need to know the precise trigger for this programmatic handshake.

I want to configure my importer so that imQueryStreamLabel is invoked unconditionally for my tests. It is essential that imQueryStreamLabel is called.

I look forward to your response.

Best regards,

[Bruce Bullis]

>What is the exact code-level condition required for the host to trigger this selector?

Honestly, we're not sure. I've confirmed in our source code, that no Adobe importer listens for or responds to that selector; it's been 20 years since that selector was introduced.

I ask again: What is the actual content of the file format you're attempting to import? 

[we can switch to DM if you like; here's my Adobe email address.]

[powerful_think1966]

I have sent my importer code via email. Please check your inbox and let me know your thoughts.
Thank you.