Skip to content

Review main-notebooks/content_extraction.ipynb #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Review main-notebooks/content_extraction.ipynb #49

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 52 additions & 52 deletions notebooks/content_extraction.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,16 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"This notebook demonstrate you can use Content Understanding API to extract semantic content from multimodal files."
"This notebook demonstrates how to use the Content Understanding API to extract semantic content from multimodal files."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity]
    • change: Corrected the sentence from "This notebook demonstrate you can use Content Understanding API to extract semantic content from multimodal files." to "This notebook demonstrates how to use the Content Understanding API to extract semantic content from multimodal files."
    • rationale: Fixed subject-verb agreement ("demonstrate" to "demonstrates") and improved sentence structure for better readability and clarity by explicitly stating "how to use."
    • impact: Enhances the professionalism and comprehensibility of the documentation, making it easier for readers to understand the notebook's purpose.

},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Prerequisites\n",
"1. Ensure Azure AI service is configured following [steps](../README.md#configure-azure-ai-service-resource)\n",
"2. Install the required packages to run the sample."
"1. Ensure your Azure AI service is configured by following the [configuration steps](../README.md#configure-azure-ai-service-resource).\n",
"2. Install the required packages to run this sample."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity, Consistency]
    • change: Reworded step 1 to "Ensure your Azure AI service is configured by following the configuration steps." and step 2 to "Install the required packages to run this sample."
    • rationale: The rewording makes the instructions more direct and personal ("your Azure AI service"), clarifies the linked content as configuration steps, and specifies "this sample" to clearly indicate the scope of the required packages.
    • impact: Improves the readability and user understanding of the setup instructions, making the documentation more approachable and precise for users following the steps.

},
{
Expand All @@ -38,14 +38,16 @@
"source": [
"## Create Azure AI Content Understanding Client\n",
"\n",
"> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class containing functions to interact with the Content Understanding API. Before the official release of the Content Understanding SDK, it can be regarded as a lightweight SDK. Fill the constant **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, **AZURE_AI_API_KEY** with the information from your Azure AI Service.\n",
"> The [AzureContentUnderstandingClient](../python/content_understanding_client.py) is a utility class that provides functions to interact with the Content Understanding API. Prior to the official release of the Content Understanding SDK, it serves as a lightweight SDK.\n",
">\n",
"> Fill in the constants **AZURE_AI_ENDPOINT**, **AZURE_AI_API_VERSION**, and **AZURE_AI_API_KEY** with the details from your Azure AI Service.\n",
"\n",
"> ⚠️ Important:\n",
"You must update the code below to match your Azure authentication method.\n",
"Look for the `# IMPORTANT` comments and modify those sections accordingly.\n",
"If you skip this step, the sample may not run correctly.\n",
"You must update the code below to use your preferred Azure authentication method.\n",
"Look for the `# IMPORTANT` comments in the code and modify those sections accordingly.\n",
"Skipping this step may cause the sample to not run correctly.\n",
"\n",
"> ⚠️ Note: Using a subscription key works, but using a token provider with Azure Active Directory (AAD) is much safer and is highly recommended for production environments."
"> ⚠️ Note: While using a subscription key is supported, it is strongly recommended to use a token provider with Azure Active Directory (AAD) for enhanced security in production environments."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity]

    • change: Reworded the description of the AzureContentUnderstandingClient for smoother flow and clearer meaning.
    • rationale: Improved sentence structure and phrasing to enhance readability and ensure the purpose of the class is clearly conveyed.
    • impact: Makes the introduction more professional and easier to understand for readers.

  • categories: [Formatting, Clarity]

    • change: Split the instruction about filling constants into a separate line with clearer phrasing and added commas between the constants.
    • rationale: Breaking the information into smaller parts improves readability; listing constants clearly helps prevent confusion.
    • impact: Enhances the visual layout and clarity, making the setup instructions easier to follow.

  • categories: [Grammar, Clarity, Consistency]

    • change: Changed “update the code below to match your Azure authentication method” to “update the code below to use your preferred Azure authentication method” and rephrased subsequent lines for clearer intent and consistency.
    • rationale: “Use your preferred” sounds more natural and empowering; rephrased sentences reduce ambiguity and improve the tone.
    • impact: Improves user guidance and reduces the risk of misunderstanding the customization needed.

  • categories: [Grammar, Clarity]

    • change: Rephrased the warning about subscription key usage to emphasize recommendation of AAD token provider and enhanced security.
    • rationale: The revised sentence more clearly and formally communicates the security recommendation.
    • impact: Provides clearer security best practices, encouraging safer usage in production environments.

},
{
Expand All @@ -66,9 +68,9 @@
"load_dotenv(find_dotenv())\n",
"logging.basicConfig(level=logging.INFO)\n",
"\n",
"# For authentication, you can use either token-based auth or subscription key, and only one of them is required\n",
"# For authentication, you can use either token-based auth or subscription key; only one is required\n",
"AZURE_AI_ENDPOINT = os.getenv(\"AZURE_AI_ENDPOINT\")\n",
"# IMPORTANT: Replace with your actual subscription key or set up in \".env\" file if not using token auth\n",
"# IMPORTANT: Replace with your actual subscription key or set it in your \".env\" file if not using token authentication\n",
"AZURE_AI_API_KEY = os.getenv(\"AZURE_AI_API_KEY\")\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity]

    • change: Replaced comma with a semicolon in the sentence about authentication methods.
    • rationale: Using a semicolon correctly separates two closely related independent clauses, improving sentence structure.
    • impact: Enhances readability and grammatical correctness of the comment.

  • categories: [Grammar, Clarity]

    • change: Changed "set up" to "set" and expanded "token auth" to "token authentication" in the instruction about setting the subscription key.
    • rationale: "Set" is the proper verb to describe assigning a value, and "token authentication" is clearer and more formal than the abbreviation "token auth."
    • impact: Improves the clarity and professionalism of the instruction, making it easier for users to understand and follow.

"AZURE_AI_API_VERSION = os.getenv(\"AZURE_AI_API_VERSION\", \"2025-05-01-preview\")\n",
"\n",
Expand All @@ -85,9 +87,9 @@
" api_version=AZURE_AI_API_VERSION,\n",
" # IMPORTANT: Comment out token_provider if using subscription key\n",
" token_provider=token_provider,\n",
" # IMPORTANT: Uncomment this if using subscription key\n",
" # IMPORTANT: Uncomment the following line if using subscription key\n",
" # subscription_key=AZURE_AI_API_KEY,\n",
" x_ms_useragent=\"azure-ai-content-understanding-python/content_extraction\", # This header is used for sample usage telemetry, please comment out this line if you want to opt out.\n",
" x_ms_useragent=\"azure-ai-content-understanding-python/content_extraction\", # This header is used for sample usage telemetry; comment out if you want to opt out.\n",
")\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity, Grammar]

    • change: Changed "Uncomment this if using subscription key" to "Uncomment the following line if using subscription key"
    • rationale: Improved clarity by explicitly indicating which line should be uncommented, and improved grammar by better specifying the action.
    • impact: Makes the instruction clearer for users, reducing potential confusion about what to uncomment.

  • categories: [Clarity, Formatting]

    • change: Modified the comment about the x_ms_useragent header from a comma-separated to a semicolon-separated sentence and slightly reworded it ("please comment out this line if you want to opt out" to "comment out if you want to opt out").
    • rationale: Using a semicolon separates the two independent clauses more correctly, and the rephrasing makes the instruction more concise and direct.
    • impact: Improves readability and clarity of the comment, making the opt-out instruction easier to understand.

"\n",
"# Utility function to save images\n",
Expand All @@ -100,6 +102,7 @@
" image_id=image_id\n",
" )\n",
" image = Image.open(BytesIO(raw_image))\n",
" # To display the image, uncomment the following line:\n",
" # image.show()\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity]
    • change: Added an explanatory comment line "# To display the image, uncomment the following line:" above the existing commented out image display code.
    • rationale: This modification provides clear guidance to the user on how to enable the image display functionality.
    • impact: Enhances the understandability of the code by explicitly instructing the user on the purpose and usage of the commented code, making the code easier to follow and use.

" Path(\".cache\").mkdir(exist_ok=True)\n",
" image.save(f\".cache/{image_id}.jpg\", \"JPEG\")\n"
Expand All @@ -111,8 +114,7 @@
"source": [
"## Document Content\n",
"\n",
"Content Understanding API is designed to extract all textual content from a specified document file. In addition to text extraction, it conducts a comprehensive layout analysis to identify and categorize tables and figures within the document. The output is then presented in a structured markdown format, ensuring clarity and ease of interpretation.\n",
"\n"
"The Content Understanding API extracts all textual content from a given document file. In addition to text extraction, it performs a thorough layout analysis to identify and categorize tables and figures within the document. The output is presented in a structured markdown format, ensuring clarity and ease of use."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity, Grammar]
    • change: Reworded the sentence from passive and somewhat verbose ("is designed to extract all textual content from a specified document file") to a more direct and active form ("extracts all textual content from a given document file"). Also replaced "conducts a comprehensive layout analysis" with "performs a thorough layout analysis," and simplified "ensuring clarity and ease of interpretation" to "ensuring clarity and ease of use." Removed an extra newline at the end.
    • rationale: To make the description more concise, direct, and easier to understand, while improving readability. The removal of the extra newline eliminates unnecessary whitespace.
    • impact: Enhances the clarity and professionalism of the documentation, making it easier for users to grasp the API’s functionality quickly and improving the overall presentation.

},
{
Expand All @@ -124,7 +126,7 @@
"ANALYZER_SAMPLE_FILE = '../data/invoice.pdf'\n",
"ANALYZER_ID = 'prebuilt-documentAnalyzer'\n",
"\n",
"# Analyzer file\n",
"# Analyze document file\n",
"response = client.begin_analyze(ANALYZER_ID, file_location=ANALYZER_SAMPLE_FILE)\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity]
    • change: Changed the comment from "# Analyzer file" to "# Analyze document file"
    • rationale: The revised comment provides a clearer description of the operation being performed, specifying that the file is being analyzed rather than just labeling it as an "analyzer file."
    • impact: Enhances the reader's understanding of the code's purpose, improving overall clarity in the documentation.

"result_json = client.poll_result(response)\n",
"\n",
Expand All @@ -135,7 +137,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"> The markdown output contains layout information, which is very useful for Retrieval-Augmented Generation (RAG) scenarios. You can paste the markdown into a viewer such as Visual Studio Code and preview the layout structure."
"> The markdown output contains detailed layout information, which is especially useful for Retrieval-Augmented Generation (RAG) scenarios. You can paste the markdown into a viewer such as Visual Studio Code to preview the layout structure."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity, Grammar]
    • change: Replaced "contains layout information, which is very useful" with "contains detailed layout information, which is especially useful"; changed "and preview the layout structure" to "to preview the layout structure."
    • rationale: The modification clarifies the type of layout information by specifying it as "detailed" and strengthens the usefulness by adding "especially." The verb construction was also improved for smoother readability.
    • impact: Enhances the precision and readability of the documentation, making it clearer why the markdown output is valuable and how to use it effectively.

},
{
Expand All @@ -144,14 +146,14 @@
"metadata": {},
"outputs": [],
"source": [
"print(result_json[\"result\"][\"contents\"][0][\"markdown\"])"
"print(result_json[\"result\"][\"contents\"][0][\"markdown\"])\n"
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Formatting]
    • change: Added a newline character \n at the end of the printed string.
    • rationale: Ensures that the printed output ends with a newline, which is typical for console output and improves readability.
    • impact: Enhances the readability of the printed output by placing subsequent console outputs on a new line.

},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"> You can get the layout information, including ```words/lines``` in the pagesnode and paragraphs info in ```paragraphs```, and ```tables``` in the table."
"> You can access layout information including `words` and `lines` within the `pages` node, paragraph details under `paragraphs`, and tables listed in the `tables` section."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Grammar, Clarity, Formatting]
    • change: Rewrote the sentence to replace awkward phrasing and inconsistent code formatting with clearer wording and uniform backticks around code terms.
    • rationale: The original sentence had unclear structure and inconsistent use of triple backticks around code elements, which was corrected to improve readability and maintain formatting consistency.
    • impact: The updated sentence is easier to understand, presents information more clearly, and follows consistent formatting conventions for inline code, enhancing the overall quality of the documentation.

},
{
Expand All @@ -167,7 +169,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"> This statement allows you to get structural information of the tables in the documents."
"> This output helps you retrieve structural information about the tables embedded within the document."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity, Grammar]
    • change: Reworded the sentence from "This statement allows you to get structural information of the tables in the documents." to "This output helps you retrieve structural information about the tables embedded within the document."
    • rationale: The revised sentence improves readability by using clearer wording and more precise phrasing, such as replacing "get" with "retrieve" and "in the documents" with "embedded within the document."
    • impact: Enhances the comprehensibility and professionalism of the documentation, making it easier for users to understand the purpose of the output.

},
{
Expand All @@ -184,17 +186,15 @@
"metadata": {},
"source": [
"## Audio Content\n",
"Our API output facilitates detailed analysis of spoken language, allowing developers to utilize the data for various applications, such as voice recognition, customer service analytics, and conversational AI. The structure of the output makes it easy to extract and analyze different components of the conversation for further processing or insights.\n",
"The API provides detailed analysis of spoken language, enabling developers to build applications such as voice recognition, customer service analytics, and conversational AI. The output structure facilitates extraction and analysis of different conversation components for further processing or insights.\n",
"\n",
"1. Speaker Identification: Each phrase is attributed to a specific speaker (in this case, \"Speaker 2\"). This allows for clarity in conversations with multiple participants.\n",
"1. Timing Information: Each transcription includes precise timing data:\n",
" - startTimeMs: The time (in milliseconds) when the phrase begins.\n",
" - endTimeMs: The time (in milliseconds) when the phrase ends.\n",
" This information is crucial for applications like video subtitles, allowing synchronization between the audio and the text.\n",
"1. Text Content: The actual spoken text is provided, which in this instance is \"Thank you for calling Woodgrove Travel.\" This is the main content of the transcription.\n",
"1. Confidence Score: Each transcription phrase includes a confidence score (0.933 in this case), indicating the likelihood that the transcription is accurate. A higher score suggests greater reliability.\n",
"1. Word-Level Breakdown: The transcription is further broken down into individual words, each with its own timing information. This allows for detailed analysis of speech patterns and can be useful for applications such as language processing or speech recognition improvement.\n",
"1. Locale Specification: The locale is specified as \"en-US,\" indicating that the transcription is in American English. This is important for ensuring that the transcription algorithms account for regional dialects and pronunciations.\n"
"Key features include:\n",
"1. **Speaker Identification:** Each phrase is linked to a specific speaker (e.g., \"Speaker 2\"), enabling clear differentiation in multi-participant conversations.\n",
"2. **Timing Information:** Each transcription includes precise start and end times (in milliseconds), crucial for applications like video subtitles and audio-text synchronization.\n",
"3. **Text Content:** The actual spoken text, such as \"Thank you for calling Woodgrove Travel,\" representing the main transcription.\n",
"4. **Confidence Score:** Each phrase has a confidence score (e.g., 0.933) indicating transcription reliability.\n",
"5. **Word-Level Breakdown:** Detailed timing for each word supports advanced speech analysis and improvements in speech recognition.\n",
"6. **Locale Specification:** The locale (e.g., \"en-US\") informs the transcription process of regional dialects and pronunciation nuances."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity, Formatting]

    • change: Rewrote the introductory paragraph to use more direct and active phrasing.
    • rationale: Active voice and concise wording improve readability and make the description clearer.
    • impact: Enhances user understanding by presenting the API capabilities in a straightforward manner.

  • categories: [Formatting, Clarity, Consistency]

    • change: Replaced multiple numbered list items all labeled “1.” with a properly numbered list (1 through 6), added bold formatting to item titles, and used consistent examples.
    • rationale: Proper numbering helps readers follow the sequence of features; bolding section titles emphasizes key points; consistent use of examples makes the content easier to scan.
    • impact: Improves readability, structure, and professional presentation of feature descriptions, aiding quicker comprehension.

  • categories: [Clarity]

    • change: Simplified and rephrased individual feature descriptions for conciseness and precision.
    • rationale: Shorter, clearer sentences avoid redundancy and make complex concepts easier to understand.
    • impact: Increases accessibility of technical information to a wider audience, facilitating better grasp of API output details.

},
{
Expand All @@ -206,7 +206,7 @@
"ANALYZER_SAMPLE_FILE = '../data/audio.wav'\n",
"ANALYZER_ID = 'prebuilt-audioAnalyzer'\n",
"\n",
"# Analyzer file\n",
"# Analyze audio file\n",
"response = client.begin_analyze(ANALYZER_ID, file_location=ANALYZER_SAMPLE_FILE)\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity]
    • change: Changed the comment from "# Analyzer file" to "# Analyze audio file"
    • rationale: The original comment was vague and could be interpreted as referring to a file related to an analyzer, whereas the revised comment clearly indicates that the code analyzes an audio file.
    • impact: Improves the clarity of the code by accurately describing its purpose, making it easier for readers to understand what the subsequent code is doing.

"result_json = client.poll_result(response)\n",
"\n",
Expand All @@ -218,14 +218,14 @@
"metadata": {},
"source": [
"## Video Content\n",
"Video output provides detailed information about audiovisual content, specifically video shots. Here are the key features it offers:\n",
"The video output provides detailed metadata about audiovisual content, specifically video shots. Key features include:\n",
"\n",
"1. Shot Information: Each shot is defined by a start and end time, along with a unique identifier. For example, Shot 0:0.0 to 0:2.800 includes a transcript and key frames.\n",
"1. Transcript: The API includes a transcript of the audio, formatted in WEBVTT, which allows for easy synchronization with the video. It captures spoken content and specifies the timing of the dialogue.\n",
"1. Key Frames: It provides a series of key frames (images) that represent important moments in the video shot, allowing users to visualize the content at specific timestamps.\n",
"1. Description: Each shot is accompanied by a description, providing context about the visuals presented. This helps in understanding the scene or subject matter without watching the video.\n",
"1. Audio Visual Metadata: Details about the video such as dimensions (width and height), type (audiovisual), and the presence of key frame timestamps are included.\n",
"1. Transcript Phrases: The output includes specific phrases from the transcript, along with timing and speaker information, enhancing the usability for applications like closed captioning or search functionalities."
"1. **Shot Information:** Each shot has a start and end time with a unique identifier. For example, Shot 0 from 0:0.0 to 0:2.800 includes a transcript and key frames.\n",
"2. **Transcript:** Audio transcripts formatted in WEBVTT facilitate synchronization with video playback.\n",
"3. **Key Frames:** A collection of key frames (images) represent important moments in the video, allowing visualization of specific timestamps.\n",
"4. **Description:** Each shot includes a descriptive summary, providing context about the visuals.\n",
"5. **AudioVisual Metadata:** Information such as video dimensions (width, height), type (audiovisual), and key frame timestamps.\n",
"6. **Transcript Phrases:** Specific dialog phrases with timing and speaker attribution enhance usability for applications like closed captioning and search."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity, Formatting]

    • change: Changed the introductory sentence to clarify that the video output provides metadata rather than just information, and rephrased to a more concise and formal tone.
    • rationale: To more precisely describe the nature of the output as metadata and improve readability with a sharper introduction.
    • impact: Provides clearer context for users, setting expectations about the type of data output, and improves the professional tone of the documentation.

  • categories: [Formatting, Clarity, Consistency]

    • change: Converted a single numbered list with repeated "1." items into a properly numbered list (1-6) with bolded feature titles and more succinct descriptions.
    • rationale: To organize the features into a clear, hierarchical, and easy-to-follow list format, making each feature distinct and visually identifiable. Bold titles improve skimmability and consistency across items.
    • impact: Enhances readability and usability of the documentation by providing a well-structured, numbered list that is easier for users to scan and understand.

  • categories: [Clarity]

    • change: Rephrased specific descriptions, e.g., simplifying explanatory text about shot times, transcript format, key frames, and metadata details for brevity and focus.
    • rationale: To reduce verbosity and potential confusion, focusing on the essential information that users need to grasp the key features quickly.
    • impact: Improves comprehension and accessibility of the documentation, enabling users to quickly ascertain important details without unnecessary complexity.

},
{
Expand All @@ -237,7 +237,7 @@
"ANALYZER_SAMPLE_FILE = '../data/FlightSimulator.mp4'\n",
"ANALYZER_ID = 'prebuilt-videoAnalyzer'\n",
"\n",
"# Analyzer file\n",
"# Analyze video file\n",
"response = client.begin_analyze(ANALYZER_ID, file_location=ANALYZER_SAMPLE_FILE)\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity]
    • change: Changed the comment from "# Analyzer file" to "# Analyze video file"
    • rationale: The original comment was vague and potentially misleading; the new comment explicitly states the purpose of the code, which is to analyze a video file.
    • impact: Improves the clarity of the code by providing a more descriptive and accurate comment, helping readers understand the code's intent more quickly.

"result_json = client.poll_result(response)\n",
"\n",
Expand All @@ -248,14 +248,13 @@
"result_data = result_json.get(\"result\", {})\n",
"contents = result_data.get(\"contents\", [])\n",
"\n",
"# Iterate over contents to find keyframes if available\n",
"# Extract keyframe IDs from markdown content\n",
"for content in contents:\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity]

    • change: Updated the comment from "Iterate over contents to find keyframes if available" to "Extract keyframe IDs from markdown content"
    • rationale: The new comment is more specific about what the loop does, clearly indicating that it is extracting keyframe IDs from markdown content rather than just iterating to find keyframes.
    • impact: Improves the clarity and understanding of the code’s purpose for future readers.

  • categories: [Clarity]

    • change: Removed the inline comment "Extract keyframe IDs from 'markdown' if it exists and is a string" before assigning and checking markdown_content
    • rationale: The operation is self-explanatory and the previous comment was redundant given the surrounding context and new, more descriptive comment above.
    • impact: Reduces unnecessary commenting, helping maintain cleaner and more readable code documentation.

" # Extract keyframe IDs from \"markdown\" if it exists and is a string\n",
" markdown_content = content.get(\"markdown\", \"\")\n",
" if isinstance(markdown_content, str):\n",
" keyframe_ids.update(re.findall(r\"(keyFrame\\.\\d+)\\.jpg\", markdown_content))\n",
"\n",
"# Output the results\n",
"# Output unique keyframe IDs\n",
"print(\"Unique Keyframe IDs:\", keyframe_ids)\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity]
    • change: Changed the comment from "# Output the results" to "# Output unique keyframe IDs"
    • rationale: The revised comment more precisely describes what the output statement is doing by specifying that unique keyframe IDs are being printed.
    • impact: This clarification helps readers and maintainers understand the purpose of the print statement more quickly and accurately.

"\n",
"# Save all keyframe images\n",
Expand All @@ -267,8 +266,10 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Video Content with Face\n",
"This is a gated feature, please go through process [Azure AI Resource Face Gating](https://learn.microsoft.com/en-us/legal/cognitive-services/computer-vision/limited-access-identity?context=%2Fazure%2Fai-services%2Fcomputer-vision%2Fcontext%2Fcontext#registration-process) Select `[Video Indexer] Facial Identification (1:N or 1:1 matching) to search for a face in a media or entertainment video archive to find a face within a video and generate metadata for media or entertainment use cases only` in the registration form."
"## Video Content with Face Recognition\n",
"This is a gated feature. To enable it, please follow the registration process outlined in [Azure AI Resource Face Gating](https://learn.microsoft.com/en-us/legal/cognitive-services/computer-vision/limited-access-identity?context=%2Fazure%2Fai-services%2Fcomputer-vision%2Fcontext%2Fcontext#registration-process).\n",
"In the registration form, select:\n",
"`[Video Indexer] Facial Identification (1:N or 1:1 matching)` to search for faces within media or entertainment video archives and generate metadata for these use cases."
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity, Grammar, Formatting]

    • change: Changed the heading from "Video Content with Face" to "Video Content with Face Recognition."
    • rationale: The new heading more accurately describes the feature being discussed.
    • impact: Improves clarity and sets correct expectations for the feature.

  • categories: [Clarity, Grammar, Formatting]

    • change: Rewrote the sentence to split it into two clearer sentences and added proper punctuation.
    • rationale: The original sentence was long, verbose, and lacked clear punctuation, making it hard to understand. Breaking it up improves readability.
    • impact: Enhances user comprehension of the gating process and registration instructions.

  • categories: [Formatting]

    • change: Reformatted the selection instruction as a bullet-like list item with quotation marks around the exact form option name.
    • rationale: Presenting the selection as a separate, clearly marked item makes it easier for users to identify the exact registration form option.
    • impact: Improves usability by helping users quickly locate the correct option in the registration form.

},
{
Expand All @@ -280,7 +281,7 @@
"ANALYZER_SAMPLE_FILE = '../data/FlightSimulator.mp4'\n",
"ANALYZER_ID = 'prebuilt-videoAnalyzer'\n",
"\n",
"# Analyzer file\n",
"# Analyze video file with face recognition\n",
"response = client.begin_analyze(ANALYZER_ID, file_location=ANALYZER_SAMPLE_FILE)\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity]
    • change: The comment was changed from "# Analyzer file" to "# Analyze video file with face recognition"
    • rationale: The updated comment provides a clearer and more descriptive explanation of what the code does.
    • impact: This enhances the reader's understanding of the code’s purpose, making the documentation more informative and useful.

"result_json = client.poll_result(response)\n",
"\n",
Expand All @@ -291,7 +292,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### Get and Save Key Frames and Face Thumbnails"
"### Retrieve and Save Key Frames and Face Thumbnails"
]
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity]
    • change: Changed the section title from "Get and Save Key Frames and Face Thumbnails" to "Retrieve and Save Key Frames and Face Thumbnails"
    • rationale: The word "Retrieve" is more precise and formal compared to "Get," improving the professionalism and clarity of the documentation.
    • impact: Enhances the readability and clarity of the documentation by using a more appropriate and descriptive verb.

},
{
Expand All @@ -300,30 +301,29 @@
"metadata": {},
"outputs": [],
"source": [
"# Initialize sets for unique face IDs and keyframe IDs\n",
"# Initialize sets to store unique face IDs and keyframe IDs\n",
"face_ids = set()\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity]
    • change: Modified the comment from "Initialize sets for unique face IDs and keyframe IDs" to "Initialize sets to store unique face IDs and keyframe IDs"
    • rationale: The new wording more clearly describes the purpose of the sets as containers for values rather than just their initialization.
    • impact: Improves the clarity of the comment, making it easier for readers to understand the role of the sets in the code.

"keyframe_ids = set()\n",
"\n",
"# Extract unique face IDs safely\n",
"# Safely extract face IDs and keyframe IDs from content\n",
"result_data = result_json.get(\"result\", {})\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity]
    • change: Updated the comment from "Extract unique face IDs safely" to "Safely extract face IDs and keyframe IDs from content"
    • rationale: The new comment more accurately and comprehensively describes the action being taken by the code, indicating both face IDs and keyframe IDs are involved and clarifying the source ("from content")
    • impact: This improves reader understanding by providing a clearer and more precise explanation of the code’s purpose, reducing potential confusion about what IDs are being extracted and from where

"contents = result_data.get(\"contents\", [])\n",
"\n",
"# Iterate over contents to find faces and keyframes if available\n",
"for content in contents:\n",
" # Safely retrieve face IDs if \"faces\" exists and is a list\n",
" # Extract face IDs if \"faces\" field exists and is a list\n",
" faces = content.get(\"faces\", [])\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity]
    • change: Removed a general comment about iterating over contents and revised a comment describing the retrieval of face IDs from "Safely retrieve face IDs if "faces" exists and is a list" to "Extract face IDs if "faces" field exists and is a list"
    • rationale: The new comment is more direct and clearer about the intent of the code that extracts face IDs, avoiding ambiguous wording like "safely retrieve."
    • impact: Enhances the readability and understanding of the code by providing a more precise and straightforward comment.

" if isinstance(faces, list):\n",
" for face in faces:\n",
" face_id = face.get(\"faceId\")\n",
" if face_id:\n",
" face_ids.add(f\"face.{face_id}\")\n",
"\n",
" # Extract keyframe IDs from \"markdown\" if it exists and is a string\n",
" # Extract keyframe IDs from \"markdown\" if present and a string\n",
" markdown_content = content.get(\"markdown\", \"\")\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity, Grammar]
    • change: Changed comment from 'if it exists and is a string' to 'if present and a string'
    • rationale: The revised phrasing is more concise and reads more smoothly, improving the clarity and grammatical structure of the comment.
    • impact: Enhances readability and comprehension of the code comment for future maintainers.

" if isinstance(markdown_content, str):\n",
" keyframe_ids.update(re.findall(r\"(keyFrame\\.\\d+)\\.jpg\", markdown_content))\n",
"\n",
"# Output the results\n",
"# Display unique face and keyframe IDs\n",
"print(\"Unique Face IDs:\", face_ids)\n",
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Clarity]
    • change: Modified the comment from "# Output the results" to "# Display unique face and keyframe IDs"
    • rationale: The new comment more precisely describes what the subsequent print statements are doing.
    • impact: Improves the clarity of the code by making the comment more descriptive and easier for readers to understand the purpose of the code block.

"print(\"Unique Keyframe IDs:\", keyframe_ids)\n",
"\n",
Expand Down Expand Up @@ -358,4 +358,4 @@
},
"nbformat": 4,
"nbformat_minor": 2
}
}
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • categories: [Formatting]
    • change: Modified the closing brace from -} to +} (adjusted line ending formatting)
    • rationale: Corrected the brace formatting to ensure proper syntax and alignment with coding style
    • impact: Improves code formatting, which aids readability and prevents potential syntax errors