Error: Only one COMM tag allowed with the same Language + Description (eng + ) however, data passed does not match this condition.

[henrydut99]

I wish to preserve all COMM frames in an id3 tag. Each frame has a different description but the same language: eng.

Here is the data away being passed to getID3 from Ampache's vainfo.php wrapper:

2025-09-19T21:26:21+00:00 [admin] (Ampache\Module\Song\Tag\SongTagWriter) -> After write_id3, $result[id3v2][COMM]: Array
(
[0] => Array
(
[frame_name] => COMM
[frame_flags_raw] => 0
[data] => POOR
[datalength] => 30
[dataoffset] => 130
[framenamelong] => Comments
[framenameshort] => comment
[flags] => Array
(
[TagAlterPreservation] =>
[FileAlterPreservation] =>
[ReadOnly] =>
[compression] =>
[Encryption] =>
[GroupingIdentity] =>
)

        [description] => MusicMatch_Preference
        [encodingid] => 0
        [encoding] => ISO-8859-1
        [language] => eng
        [languagename] => English
    )

[1] => Array
    (
        [frame_name] => COMM
        [frame_flags_raw] => 0
        [data] => Comment set but user to rememeber track details.
        [datalength] => 49
        [dataoffset] => 1234
        [framenamelong] => Comments
        [framenameshort] => comment
        [flags] => Array
            (
                [TagAlterPreservation] =>
                [FileAlterPreservation] =>
                [ReadOnly] =>
                [compression] =>
                [Encryption] =>
                [GroupingIdentity] =>
            )

        [description] =>
        [encodingid] => 0
        [encoding] => ISO-8859-1
        [language] => eng
        [languagename] => English
    )

[2] => Array
    (
        [frame_name] => COMM
        [frame_flags_raw] => 0
        [data] => Excellent copy
        [datalength] => 38
        [dataoffset] => 1620
        [framenamelong] => Comments
        [framenameshort] => comment
        [flags] => Array
            (
                [TagAlterPreservation] =>
                [FileAlterPreservation] =>
                [ReadOnly] =>
                [compression] =>
                [Encryption] =>
                [GroupingIdentity] =>
            )

        [description] => SONGS-DB_PREFERENCE
        [encodingid] => 0
        [encoding] => ISO-8859-1
        [language] => eng
        [languagename] => English
    )

)

here is what getid3 returns:

2025-09-19T21:26:21+00:00 [admin] (Ampache\Module\Util\VaInfo) -> [DynamicEncCode] Error Writing Tags: WriteID3v2() failed with message(s):

Only one COMM tag allowed with the same Language + Description (eng + )
Frame "COMM" is NOT allowed
$this->GenerateID3v2FrameData() failed for "COMM"
$this->GenerateID3v2Tag() failed

however as you can see from inspecting the data array, the data does not match the error. Each COMM frame has a different description and the same language "eng". The frames with descriptions are set by software after analyzing the mp3 structure. The COMM frame with no description is set by tagging software. I wish to keep all three as they all contain valuable data.

Why is this data set throwing this error? Is it a bug or is the error description inaccurate?

[JamesHeinrich]

From the error message it's seeing the language eng but not the description (emptystring). You do have one entry with an empty description, but one entry like that should be fine as long as the others have a non-empty description, which your data seems to show.

It would be useful if you could try tracing back to see where that data gets lost, for example before write.id3v2.php:1639 insert a print_r($source_data_array); to see what's getting passed to ID3v2FrameIsAllowed.

[henrydut99]

Here is the result of 16 hours of excruciating prodding of grok and copilot. As I am unfamiliar with both the Ampache code base and getID3 it takes a long time to find the right prompts to track down these type of issues.

They were able to track down the bug by tracing the code (many times) all the way from a writerating action in Ampache's songtagwriter which reconstructs the id3 frame by reading all frames and writing them back along with the modified POPM value. Songtagwriter uses vainfo which is a wrapper for getid3.

I have very high confidence that the analysis is correct. I have been working on techniques to validate each answer against a known good state with progressive prompting. There is also a specific code fix suggestion however I have not tested it yet. Based on past experience, I believe it could be close to, or a working solution. I was going to make the code change on this installation locally and test it but better to inform you about it.

This is the high level summary of the findings with a proposed code solution:

Bug: Multiple COMM Frames with Unique Descriptions Treated as Duplicates with Empty Descriptions in ID3v2 Writer

Affected Version: Latest development branch (as of September 2025;

Description

The ID3v2 writer in write.id3v2.php incorrectly handles multiple COMM (Comments) frames when $tag_data['comment'] is provided as an associative array, where keys represent the "Short content descrip." field and values represent the comment data. Instead of using the keys as descriptions, the writer ignores them and defaults all descriptions to an empty string (''). This causes all COMM frames to be treated as having the same language + description pair (e.g., eng + ), triggering the uniqueness check error:

Only one COMM tag allowed with the same Language + Description (eng + )

This results in the entire tag write failing. The behavior violates the ID3v2 specification, which allows multiple COMM frames as long as each has a unique language + description combination. It also breaks compatibility with the getID3 reader, which correctly parses COMM frames into an associative array with descriptions as keys.

Steps to Reproduce

1. Prepare an ID3v2 tag data array with multiple COMM frames using associative keys for descriptions:

   $tag_data['comment'] = [
       'Preference1' => 'Value1',
       'Preference2' => 'Value2',
       'CustomComment' => 'Custom comment text'
   ];

2. Initialize a getid3_writetags object:

   $tagWriter = new getid3_writetags();
   $tagWriter->filename = 'test.mp3';
   $tagWriter->tagformats = ['id3v2.3'];
   $tagWriter->tag_encoding = 'ISO-8859-1';
   $tagWriter->tag_data = $tag_data;

3. Call $tagWriter->WriteTags().
4. Check $tagWriter->errors for the error:

   Only one COMM tag allowed with the same Language + Description (eng + )
   

Expected Behavior

• The writer should generate three COMM frames with unique descriptions (Preference1, Preference2, CustomComment), language eng, and the corresponding data.
• The uniqueness check in ID3v2FrameIsAllowed() should pass, as each frame has a unique language + description pair.
• The tag write should succeed, and the file's ID3v2 tag should include the three COMM frames.

Actual Behavior

• All COMM frames are treated as having description = '', resulting in multiple eng + '' frames.
• The uniqueness check fails on the second and third frames, producing the error above.
• The entire tag write fails, and no changes are applied to the file.

Evidence from Logs (Generalized)

• Input to Writer: The $tag_data['comment'] array is correctly formatted as an associative array:

  Array
  (
      [Preference1] => Value1
      [Preference2] => Value2
      [CustomComment] => Custom comment text
  )
  

• Pre-Write Debug Output: Confirms the input structure is passed to the writer as expected.
• Writer Error Output: Reports the duplicate error:

  Only one COMM tag allowed with the same Language + Description (eng + )
  

• Post-Write Analysis: The ID3v2 tag remains unchanged, with no new COMM frames written.
• Hex Dump: Analysis of the file post-write shows no modifications, confirming the write failure.

This behavior is consistent across tests with ID3v2.3 tags, indicating a bug in the writer's handling of associative comment arrays.

Root Cause

The bug is in the WriteID3v2() method of write.id3v2.php, specifically in the loop that processes $this->tag_data:

foreach ($this->tag_data as $frame_name => $frame_rawinputdata) {
    foreach ($frame_rawinputdata as $irrelevantindex => $source_data_array) {
        // ...
    }
}

For $frame_name = 'comment', $frame_rawinputdata is an associative array ([desc => value]), but the inner foreach treats each entry as a $source_data_array (a string, e.g., 'Value1'). This causes ID3v2FrameIsAllowed() to see description as unset (defaulting to '') and language as unset (defaulting to 'eng' in GenerateID3v2FrameData()). As a result, all COMM frames are treated as eng + '', triggering the duplicate error in:

if (in_array($frame_name.$source_data_array['language'].$source_data_array['description'], $PreviousFrames)) {
    $this->errors[] = 'Only one '.$frame_name.' tag allowed with the same Language + Description ('.$source_data_array['language'].' + '.$source_data_array['description'].')';
}

Proposed Fix

Modify WriteID3v2() to add special handling for $frame_name === 'comment', using the associative keys as descriptions and setting defaults for language and encodingid. This ensures each COMM frame has a unique language + description pair.

Patch (diff format):

--- a/getid3/write.id3v2.php
+++ b/getid3/write.id3v2.php
@@ -595,6 +595,22 @@ public function WriteID3v2() {
 		if (is_array($this->tag_data)) {
 			foreach ($this->tag_data as $frame_name => $frame_rawinputdata) {
+				if ($frame_name === 'comment') {
+					// Special handling for COMM frames to use associative keys as descriptions
+					foreach ($frame_rawinputdata as $description => $data) {
+						$source_data_array = [
+							'encodingid' => $this->id3v2_default_encodingid,
+							'language' => 'eng',
+							'description' => is_numeric($description) ? '' : $description,
+							'data' => is_array($data) ? implode("\n", $data) : $data
+						];
+						if ($this->ID3v2FrameIsAllowed($frame_name, $source_data_array)) {
+							if ($frame_data = $this->GenerateID3v2FrameData($frame_name, $source_data_array)) {
+								$FrameUnsynchronisation = false;
+								// ... rest of frame processing (same as below) ...
+							}
+						}
+					}
+				} else {
 				foreach ($frame_rawinputdata as $irrelevantindex => $source_data_array) {
 					if (getid3_id3v2::IsValidID3v2FrameName($frame_name, $this->majorversion)) {
 						if ($this->ID3v2FrameIsAllowed($frame_name, $source_data_array)) {
@@ -626,7 +642,7 @@ public function WriteID3v2() {
 							}
 						}
 					}
+				}
 			}
 		}

Impact and Compatibility:

• The patch preserves all COMM frames with unique descriptions, aligning with the ID3v2 specification.
• It maintains compatibility with ID3v2.3 and ID3v2.4, using default language = 'eng' and encodingid = 0 (ISO-8859-1).
• No breaking changes, as it only affects comment frame handling.
• Matches the getID3 reader's behavior, which parses COMM frames into [desc => value] arrays.

Suggested Next Steps

• Apply the patch and verify it resolves the issue with unit tests.
• Add a unit test to tests/ for multiple COMM frames with associative arrays:

  public function testMultipleCommFrames() {
      $tagWriter = new getid3_writetags();
      $tagWriter->filename = 'test.mp3';
      $tagWriter->tagformats = ['id3v2.3'];
      $tagWriter->tag_encoding = 'ISO-8859-1';
      $tagWriter->tag_data = [
          'comment' => [
              'Preference1' => 'Value1',
              'Preference2' => 'Value2',
              'CustomComment' => 'Custom comment text'
          ]
      ];
      $this->assertTrue($tagWriter->WriteTags());
      $this->assertEmpty($tagWriter->errors);
      // Verify file has three COMM frames with correct descriptions
  }

• Consider documenting the expected $tag_data['comment'] format in README.md to clarify that keys are used as descriptions.

Additional Notes

• The bug was identified in the context of an application (Ampache) writing multiple COMM frames, but it affects any use case with associative comment arrays.
• Ampache with the Write_tags=on setting is a bit of a tag destroyer in that it makes a lot of assumptions on what the user wants when writing id3 tags- adding some, removing others. I have been modifying it to preserve the frames to be identical going in and coming out of a read and write process. This is how I discovered the issue. mpeg correctness scanning software wrote those two comment frames based on an analysis of the mp3 file and they are useful data to keep. Other tag writers write simple tag comments with "" (no description) so this is a real world scenario. The user would like to preserve all this data as it is useful.
• Thank you!

[JamesHeinrich]

Thank you for your analysis. If you want to submit a PR fixing the problem it would be much appreciated.

[henrydut99]

Thank you for your analysis. If you want to submit a PR fixing the problem it would be much appreciated.

I don't know how to do that yet. I was hoping you would be able to understand the issue and fix it.

I know that I have tested this extensively. > 1 COMM frame even if they have unique desc + language (as the example I gave above) despite being valid according the the spec will always result in this error and will fail to write.

[henrydut99]

Okay I tried implementing the code change as described and it didn't work. Here is the data extracted from the COMM frames:

(
    [0] => Array
        (
            [frame_name] => COMM
            [frame_flags_raw] => 0
            [data] => POOR
            [datalength] => 30
            [dataoffset] => 130
            [framenamelong] => Comments
            [framenameshort] => comment
            [flags] => Array
                (
                    [TagAlterPreservation] =>
                    [FileAlterPreservation] =>
                    [ReadOnly] =>
                    [compression] =>
                    [Encryption] =>
                    [GroupingIdentity] =>
                )

            [description] => MusicMatch_Preference
            [encodingid] => 0
            [encoding] => ISO-8859-1
            [language] => eng
            [languagename] => English
        )

    [1] => Array
        (
            [frame_name] => COMM
            [frame_flags_raw] => 0
            [data] => value
            [datalength] => 49
            [dataoffset] => 1234
            [framenamelong] => Comments
            [framenameshort] => comment
            [flags] => Array
                (
                    [TagAlterPreservation] =>
                    [FileAlterPreservation] =>
                    [ReadOnly] =>
                    [compression] =>
                    [Encryption] =>
                    [GroupingIdentity] =>
                )

            [description] =>
            [encodingid] => 0
            [encoding] => ISO-8859-1
            [language] => eng
            [languagename] => English
        )

    [2] => Array
        (
            [frame_name] => COMM
            [frame_flags_raw] => 0
            [data] => Excellent copy
            [datalength] => 38
            [dataoffset] => 1620
            [framenamelong] => Comments
            [framenameshort] => comment
            [flags] => Array
                (
                    [TagAlterPreservation] =>
                    [FileAlterPreservation] =>
                    [ReadOnly] =>
                    [compression] =>
                    [Encryption] =>
                    [GroupingIdentity] =>
                )

            [description] => SONGS-DB_PREFERENCE
            [encodingid] => 0
            [encoding] => ISO-8859-1
            [language] => eng
            [languagename] => English
        )

)

here is debug logs from different stages getting the data ready to write:

2025-09-20T14:40:36+00:00 [admin] (Ampache\Module\Util\VaInfo) -> [grok] ^^^^^^^^^^^^^^^^^^^^Tag data[comment] being written to /media/40/102.mp3: Array
(
    [MusicMatch_Preference] => POOR
    [SONGS-DB_PREFERENCE] => Excellent copy
    [CustomComment] => value
)


2025-09-20T14:40:36+00:00 [admin] (Ampache\Module\Song\Tag\SongTagWriter) -> FINAL $ndata[comment] (about to write*****************************): Array
(
    [MusicMatch_Preference] => POOR
    [SONGS-DB_PREFERENCE] => Excellent copy
    [CustomComment] => value
)

2025-09-20T14:40:36+00:00 [admin] (Ampache\Module\Song\Tag\SongTagWriter) -> About to process id3v2Data[comment] for multi-frame tags: Array
(
    [MusicMatch_Preference] => POOR
    [0] => value
    [SONGS-DB_PREFERENCE] => Excellent copy
)

2025-09-20T14:40:36+00:00 [admin] (Ampache\Module\Song\Tag\SongTagWriter) -> +++++++++++++++++++++++++About to process id3v2Data for multi-frame tags: Array
(
    [comment] => Array
        (
            [MusicMatch_Preference] => POOR
            [0] => value
            [SONGS-DB_PREFERENCE] => Excellent copy
        )

but it still ends up with a failed write:

2025-09-20T14:40:36+00:00 [admin] (Ampache\Module\Util\VaInfo) -> [DynamicEncCode] Error Writing Tags: WriteID3v2() failed with message(s):<pre><ul><li>Only one COMM tag allowed with the same Language + Description (eng + )</li><li>Frame &quot;COMM&quot; is NOT allowed</li><li>$this-&gt;GenerateID3v2FrameData() failed for &quot;COMM&quot;</li><li>$this-&gt;GenerateID3v2Tag() failed</li></ul></pre>

[henrydut99]

I removed the COMM with the empty description just two comments each with a unique description and both with eng language. Same result:

Error Writing Tags: WriteID3v2() failed with message(s):

Only one COMM tag allowed with the same Language + Description (eng + )
Frame "COMM" is NOT allowed
$this->GenerateID3v2FrameData() failed for "COMM"
$this->GenerateID3v2Tag() failed

So it seems the code will only allow one COMM frame in total even though the spec allows multiple frames.

[JamesHeinrich]

So it seems the code will only allow one COMM frame in total even though the spec allows multiple frames.
Yes, as said before the description is somehow being lost between GenerateID3v2Tag and ID3v2FrameIsAllowed, we just have to figure out where and why.

I don't have a ready testing setup for this problem, if you could supply a sample file and simple code to replicate the problem it would go a long way to me being able to find and fix the problem.