[ContentUnderstanding] Add ContentRange samples for document, video, and audio.

sdk/contentunderstanding/azure-ai-contentunderstanding/assets.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "python",
   "TagPrefix": "python/contentunderstanding/azure-ai-contentunderstanding",
-  "Tag": "python/contentunderstanding/azure-ai-contentunderstanding_8f5aa72c31"
+  "Tag": "python/contentunderstanding/azure-ai-contentunderstanding_4b81bc4b88"
 }

sdk/contentunderstanding/azure-ai-contentunderstanding/azure/ai/contentunderstanding/_patch.py

@@ -247,8 +247,9 @@ def begin_analyze_binary(
         :type analyzer_id: str
         :param binary_input: The binary content of the document to analyze. Required.
         :type binary_input: bytes
-        :keyword content_range: Range of the input to analyze (ex. ``1-3,5,9-``). Document content uses
-         1-based page numbers, while audio visual content uses integer milliseconds. Default value is None.
+        :keyword content_range: Range of the input to analyze. Accepts a raw string
+         (ex. ``"1-3,5,9-"``). Document content uses 1-based page numbers,
+         while audio visual content uses integer milliseconds. Default value is None.
         :paramtype content_range: str
         :keyword content_type: Body Parameter content-type. Content type parameter for binary body.
          Default value is "application/octet-stream".

sdk/contentunderstanding/azure-ai-contentunderstanding/azure/ai/contentunderstanding/aio/_patch.py

@@ -248,8 +248,9 @@ async def begin_analyze_binary(
         :type analyzer_id: str
         :param binary_input: The binary content of the document to analyze. Required.
         :type binary_input: bytes
-        :keyword content_range: Range of the input to analyze (ex. ``1-3,5,9-``). Document content uses
-         1-based page numbers, while audio visual content uses integer milliseconds. Default value is None.
+        :keyword content_range: Range of the input to analyze. Accepts a raw string
+         (ex. ``"1-3,5,9-"``). Document content uses 1-based page numbers,
+         while audio visual content uses integer milliseconds. Default value is None.
         :paramtype content_range: str
         :keyword content_type: Body Parameter content-type. Content type parameter for binary body.
          Default value is "application/octet-stream".

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_analyze_binary_async.py

@@ -89,6 +89,47 @@ async def main() -> None:
         result: AnalysisResult = await poller.result()
         # [END analyze_document_from_binary]
 
+        # [START analyze_binary_with_content_range]
+        # Use a multi-page document for content range demonstrations.
+        multi_page_path = "sample_files/mixed_financial_invoices.pdf"
+        with open(multi_page_path, "rb") as f:
+            multi_page_bytes = f.read()
+
+        # Analyze only pages 3 onward.
+        print("\nAnalyzing pages 3 onward with content range '3-'...")
+        range_poller = await client.begin_analyze_binary(
+            analyzer_id="prebuilt-documentSearch",
+            binary_input=multi_page_bytes,
+            content_range="3-",
+        )
+        range_result: AnalysisResult = await range_poller.result()
+
+        if isinstance(range_result.contents[0], DocumentContent):
+            range_doc = range_result.contents[0]
+            print(
+                f"Content range analysis returned pages"
+                f" {range_doc.start_page_number} - {range_doc.end_page_number}"
+            )
+        # [END analyze_binary_with_content_range]
+
+        # [START analyze_binary_with_combined_content_range]
+        # Analyze pages 1-3, page 5, and pages 9 onward.
+        print("\nAnalyzing combined pages (1-3, 5, 9-) with content range '1-3,5,9-'...")
+        combine_range_poller = await client.begin_analyze_binary(
+            analyzer_id="prebuilt-documentSearch",
+            binary_input=multi_page_bytes,
+            content_range="1-3,5,9-",
+        )
+        combine_range_result: AnalysisResult = await combine_range_poller.result()
+
+        if isinstance(combine_range_result.contents[0], DocumentContent):
+            combine_doc = combine_range_result.contents[0]
+            print(
+                f"Combined content range analysis returned pages"
+                f" {combine_doc.start_page_number} - {combine_doc.end_page_number}"
+            )
+        # [END analyze_binary_with_combined_content_range]
+
         # [START extract_markdown]
         print("\nMarkdown Content:")
         print("=" * 50)

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_analyze_url_async.py

@@ -72,7 +72,7 @@ async def main() -> None:
         print("DOCUMENT ANALYSIS FROM URL")
         print("=" * 60)
         # You can replace this URL with your own publicly accessible document URL.
-        document_url = "https://raw.githubusercontent.com/Azure-Samples/azure-ai-content-understanding-assets/main/document/invoice.pdf"
+        document_url = "https://raw.githubusercontent.com/Azure-Samples/azure-ai-content-understanding-assets/main/document/mixed_financial_docs.pdf"
 
         print(f"Analyzing document from URL with prebuilt-documentSearch...")
         print(f"  URL: {document_url}")
@@ -104,6 +104,23 @@ async def main() -> None:
                 print(f"  Page {page.page_number}: {page.width} x {page.height} {unit}")
         # [END analyze_document_from_url]
 
+        # [START analyze_document_url_with_content_range]
+        # Restrict to specific pages with a content range string.
+        # Extract only page 1 of the document.
+        print("\nAnalyzing page 1 only with content range '1'...")
+        range_poller = await client.begin_analyze(
+            analyzer_id="prebuilt-documentSearch",
+            inputs=[AnalysisInput(url=document_url, content_range="1")],
+        )
+        range_result: AnalysisResult = await range_poller.result()
+
+        range_doc_content = cast(DocumentContent, range_result.contents[0])
+        print(
+            f"Content range analysis returned pages"
+            f" {range_doc_content.start_page_number} - {range_doc_content.end_page_number}"
+        )
+        # [END analyze_document_url_with_content_range]
+
         # [START analyze_video_from_url]
         print("\n" + "=" * 60)
         print("VIDEO ANALYSIS FROM URL")
@@ -145,6 +162,90 @@ async def main() -> None:
             segment_index += 1
         # [END analyze_video_from_url]
 
+        # [START analyze_video_url_with_content_range]
+        # Restrict to a time window with a content range string.
+        # Analyze only the first 5 seconds of the video (milliseconds: "0-5000").
+        print("\nAnalyzing first 5 seconds of video with content range '0-5000'...")
+        video_range_poller = await client.begin_analyze(
+            analyzer_id="prebuilt-videoSearch",
+            inputs=[
+                AnalysisInput(
+                    url=video_url,
+                    content_range="0-5000",
+                )
+            ],
+        )
+        video_range_result = await video_range_poller.result()
+
+        for range_media in video_range_result.contents:
+            range_video_content = cast(AudioVisualContent, range_media)
+            print(
+                f"Content range segment:"
+                f" {range_video_content.start_time_ms} ms - {range_video_content.end_time_ms} ms"
+            )
+        # [END analyze_video_url_with_content_range]
+
+        # [START analyze_video_url_with_additional_content_ranges]
+        # Additional content range examples for video (time ranges use milliseconds):
+
+        # "10000-" — analyze from 10 seconds onward
+        print("\nAnalyzing video from 10 seconds onward with content range '10000-'...")
+        video_from_poller = await client.begin_analyze(
+            analyzer_id="prebuilt-videoSearch",
+            inputs=[
+                AnalysisInput(
+                    url=video_url,
+                    content_range="10000-",
+                )
+            ],
+        )
+        video_from_result = await video_from_poller.result()
+        for from_media in video_from_result.contents:
+            from_video = cast(AudioVisualContent, from_media)
+            print(
+                f"'10000-' segment:"
+                f" {from_video.start_time_ms} ms - {from_video.end_time_ms} ms"
+            )
+
+        # "1200-3651" — sub-second precision (1.2s to 3.651s)
+        print("\nAnalyzing video with sub-second precision (1.2s to 3.651s) with content range '1200-3651'...")
+        video_subsec_poller = await client.begin_analyze(
+            analyzer_id="prebuilt-videoSearch",
+            inputs=[
+                AnalysisInput(
+                    url=video_url,
+                    content_range="1200-3651",
+                )
+            ],
+        )
+        video_subsec_result = await video_subsec_poller.result()
+        for subsec_media in video_subsec_result.contents:
+            subsec_video = cast(AudioVisualContent, subsec_media)
+            print(
+                f"'1200-3651' segment:"
+                f" {subsec_video.start_time_ms} ms - {subsec_video.end_time_ms} ms"
+            )
+
+        # "0-3000,30000-" — multiple disjoint time ranges (0-3s and 30s onward)
+        print("\nAnalyzing video with combined time ranges (0-3s and 30s onward) with content range '0-3000,30000-'...")
+        video_combine_poller = await client.begin_analyze(
+            analyzer_id="prebuilt-videoSearch",
+            inputs=[
+                AnalysisInput(
+                    url=video_url,
+                    content_range="0-3000,30000-",
+                )
+            ],
+        )
+        video_combine_result = await video_combine_poller.result()
+        for combine_media in video_combine_result.contents:
+            combine_video = cast(AudioVisualContent, combine_media)
+            print(
+                f"'0-3000,30000-' segment:"
+                f" {combine_video.start_time_ms} ms - {combine_video.end_time_ms} ms"
+            )
+        # [END analyze_video_url_with_additional_content_ranges]
+
         # [START analyze_audio_from_url]
         print("\n" + "=" * 60)
         print("AUDIO ANALYSIS FROM URL")
@@ -181,6 +282,86 @@ async def main() -> None:
                 print(f"  [{phrase.speaker}] {phrase.start_time_ms} ms: {phrase.text}")
         # [END analyze_audio_from_url]
 
+        # [START analyze_audio_url_with_content_range]
+        # Restrict to a time window with a content range string.
+        # Analyze only the first 5 seconds of the audio (milliseconds: "0-5000").
+        print("\nAnalyzing first 5 seconds of audio with content range '0-5000'...")
+        audio_range_poller = await client.begin_analyze(
+            analyzer_id="prebuilt-audioSearch",
+            inputs=[
+                AnalysisInput(
+                    url=audio_url,
+                    content_range="0-5000",
+                )
+            ],
+        )
+        audio_range_result = await audio_range_poller.result()
+
+        range_audio_content = cast(AudioVisualContent, audio_range_result.contents[0])
+        print(
+            f"Content range audio segment:"
+            f" {range_audio_content.start_time_ms} ms - {range_audio_content.end_time_ms} ms"
+        )
+        # [END analyze_audio_url_with_content_range]
+
+        # [START analyze_audio_url_with_additional_content_ranges]
+        # Additional content range examples for audio (time ranges use milliseconds):
+
+        # "10000-" — analyze from 10 seconds onward
+        print("\nAnalyzing audio from 10 seconds onward with content range '10000-'...")
+        audio_from_poller = await client.begin_analyze(
+            analyzer_id="prebuilt-audioSearch",
+            inputs=[
+                AnalysisInput(
+                    url=audio_url,
+                    content_range="10000-",
+                )
+            ],
+        )
+        audio_from_result = await audio_from_poller.result()
+        audio_from_content = cast(AudioVisualContent, audio_from_result.contents[0])
+        print(
+            f"'10000-':"
+            f" {audio_from_content.start_time_ms} ms - {audio_from_content.end_time_ms} ms"
+        )
+
+        # "1200-3651" — sub-second precision (1.2s to 3.651s)
+        print("\nAnalyzing audio with sub-second precision (1.2s to 3.651s) with content range '1200-3651'...")
+        audio_subsec_poller = await client.begin_analyze(
+            analyzer_id="prebuilt-audioSearch",
+            inputs=[
+                AnalysisInput(
+                    url=audio_url,
+                    content_range="1200-3651",
+                )
+            ],
+        )
+        audio_subsec_result = await audio_subsec_poller.result()
+        audio_subsec_content = cast(AudioVisualContent, audio_subsec_result.contents[0])
+        print(
+            f"'1200-3651':"
+            f" {audio_subsec_content.start_time_ms} ms - {audio_subsec_content.end_time_ms} ms"
+        )
+
+        # "0-3000,30000-" — multiple disjoint time ranges (0-3s and 30s onward)
+        print("\nAnalyzing audio with combined time ranges (0-3s and 30s onward) with content range '0-3000,30000-'...")
+        audio_combine_poller = await client.begin_analyze(
+            analyzer_id="prebuilt-audioSearch",
+            inputs=[
+                AnalysisInput(
+                    url=audio_url,
+                    content_range="0-3000,30000-",
+                )
+            ],
+        )
+        audio_combine_result = await audio_combine_poller.result()
+        audio_combine_content = cast(AudioVisualContent, audio_combine_result.contents[0])
+        print(
+            f"'0-3000,30000-':"
+            f" {audio_combine_content.start_time_ms} ms - {audio_combine_content.end_time_ms} ms"
+        )
+        # [END analyze_audio_url_with_additional_content_ranges]
+
         # [START analyze_image_from_url]
         print("\n" + "=" * 60)
         print("IMAGE ANALYSIS FROM URL")

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/sample_analyze_binary.py

@@ -87,6 +87,41 @@ def main() -> None:
     result: AnalysisResult = poller.result()
     # [END analyze_document_from_binary]
 
+    # [START analyze_binary_with_content_range]
+    # Use a multi-page document for content range demonstrations.
+    multi_page_path = "sample_files/mixed_financial_invoices.pdf"
+    with open(multi_page_path, "rb") as f:
+        multi_page_bytes = f.read()
+
+    # Analyze only pages 3 onward.
+    print("\nAnalyzing pages 3 onward with content range '3-'...")
+    range_poller = client.begin_analyze_binary(
+        analyzer_id="prebuilt-documentSearch",
+        binary_input=multi_page_bytes,
+        content_range="3-",
+    )
+    range_result: AnalysisResult = range_poller.result()
+
+    if isinstance(range_result.contents[0], DocumentContent):
+        range_doc = range_result.contents[0]
+        print(f"Content range analysis returned pages {range_doc.start_page_number} - {range_doc.end_page_number}")
+    # [END analyze_binary_with_content_range]
+
+    # [START analyze_binary_with_combined_content_range]
+    # Analyze pages 1-3, page 5, and pages 9 onward.
+    print("\nAnalyzing combined pages (1-3, 5, 9-) with content range '1-3,5,9-'...")
+    combine_range_poller = client.begin_analyze_binary(
+        analyzer_id="prebuilt-documentSearch",
+        binary_input=multi_page_bytes,
+        content_range="1-3,5,9-",
+    )
+    combine_range_result: AnalysisResult = combine_range_poller.result()
+
+    if isinstance(combine_range_result.contents[0], DocumentContent):
+        combine_doc = combine_range_result.contents[0]
+        print(f"Combined content range analysis returned pages {combine_doc.start_page_number} - {combine_doc.end_page_number}")
+    # [END analyze_binary_with_combined_content_range]
+
     # [START extract_markdown]
     print("\nMarkdown Content:")
     print("=" * 50)