pixeltable 0.4.0rc3__py3-none-any.whl → 0.4.20__py3-none-any.whl

pixeltable/func/signature.py

@@ -4,7 +4,7 @@ import dataclasses
 import inspect
 import logging
 import typing
-from typing import TYPE_CHECKING, Any, Callable, ClassVar, Optional
+from typing import TYPE_CHECKING, Any, Callable, ClassVar
 
 import pixeltable.exceptions as excs
 import pixeltable.type_system as ts
@@ -18,11 +18,11 @@ _logger = logging.getLogger('pixeltable')
 @dataclasses.dataclass
 class Parameter:
     name: str
-    col_type: Optional[ts.ColumnType]  # None for variable parameters
+    col_type: ts.ColumnType | None  # None for variable parameters
     kind: inspect._ParameterKind
     # for some reason, this needs to precede is_batched in the dataclass definition,
     # otherwise Python complains that an argument with a default is followed by an argument without a default
-    default: Optional['exprs.Literal'] = None  # default value for the parameter
+    default: 'exprs.Literal' | None = None  # default value for the parameter
     is_batched: bool = False  # True if the parameter is a batched parameter (eg, Batch[dict])
 
     def __post_init__(self) -> None:
@@ -84,8 +84,28 @@ class Signature:
     """
 
     SPECIAL_PARAM_NAMES: ClassVar[list[str]] = ['group_by', 'order_by']
-
-    def __init__(self, return_type: ts.ColumnType, parameters: list[Parameter], is_batched: bool = False):
+    SYSTEM_PARAM_NAMES: ClassVar[list[str]] = ['_runtime_ctx']
+
+    return_type: ts.ColumnType
+    is_batched: bool
+    parameters: dict[str, Parameter]  # name -> Parameter
+    parameters_by_pos: list[Parameter]  # ordered by position in the signature
+    constant_parameters: list[Parameter]  # parameters that are not batched
+    batched_parameters: list[Parameter]  # parameters that are batched
+    required_parameters: list[Parameter]  # parameters that do not have a default value
+
+    # the names of recognized system parameters in the signature; these are excluded from self.parameters
+    system_parameters: list[str]
+
+    py_signature: inspect.Signature
+
+    def __init__(
+        self,
+        return_type: ts.ColumnType,
+        parameters: list[Parameter],
+        is_batched: bool = False,
+        system_parameters: list[str] | None = None,
+    ):
         assert isinstance(return_type, ts.ColumnType)
         self.return_type = return_type
         self.is_batched = is_batched
@@ -95,6 +115,7 @@ class Signature:
         self.constant_parameters = [p for p in parameters if not p.is_batched]
         self.batched_parameters = [p for p in parameters if p.is_batched]
         self.required_parameters = [p for p in parameters if not p.has_default()]
+        self.system_parameters = system_parameters if system_parameters is not None else []
         self.py_signature = inspect.Signature([p.to_py_param() for p in self.parameters_by_pos])
 
     def get_return_type(self) -> ts.ColumnType:
@@ -151,7 +172,7 @@ class Signature:
 
         return True
 
-    def validate_args(self, bound_args: dict[str, Optional['exprs.Expr']], context: str = '') -> None:
+    def validate_args(self, bound_args: dict[str, 'exprs.Expr' | None], context: str = '') -> None:
         if context:
             context = f' ({context})'
 
@@ -210,11 +231,11 @@ class Signature:
         return f'({", ".join(param_strs)}) -> {self.get_return_type()}'
 
     @classmethod
-    def _infer_type(cls, annotation: Optional[type]) -> tuple[Optional[ts.ColumnType], Optional[bool]]:
+    def _infer_type(cls, annotation: type | None) -> tuple[ts.ColumnType | None, bool | None]:
         """Returns: (column type, is_batched) or (None, ...) if the type cannot be inferred"""
         if annotation is None:
             return (None, None)
-        py_type: Optional[type] = None
+        py_type: type | None = None
         is_batched = False
         if typing.get_origin(annotation) == typing.Annotated:
             type_args = typing.get_args(annotation)
@@ -231,12 +252,13 @@ class Signature:
     @classmethod
     def create_parameters(
         cls,
-        py_fn: Optional[Callable] = None,
-        py_params: Optional[list[inspect.Parameter]] = None,
-        param_types: Optional[list[ts.ColumnType]] = None,
-        type_substitutions: Optional[dict] = None,
+        py_fn: Callable | None = None,
+        py_params: list[inspect.Parameter] | None = None,
+        param_types: list[ts.ColumnType] | None = None,
+        type_substitutions: dict | None = None,
         is_cls_method: bool = False,
     ) -> list[Parameter]:
+        """Ignores parameters starting with '_'."""
         from pixeltable import exprs
 
         assert (py_fn is None) != (py_params is None)
@@ -251,6 +273,10 @@ class Signature:
         for idx, param in enumerate(py_params):
             if is_cls_method and idx == 0:
                 continue  # skip 'self' or 'cls' parameter
+            if param.name in cls.SYSTEM_PARAM_NAMES:
+                continue  # skip system parameters
+            if param.name.startswith('_'):
+                raise excs.Error(f"{param.name!r}: parameters starting with '_' are reserved")
             if param.name in cls.SPECIAL_PARAM_NAMES:
                 raise excs.Error(f'{param.name!r} is a reserved parameter name')
             if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
@@ -284,9 +310,9 @@ class Signature:
     def create(
         cls,
         py_fn: Callable,
-        param_types: Optional[list[ts.ColumnType]] = None,
-        return_type: Optional[ts.ColumnType] = None,
-        type_substitutions: Optional[dict] = None,
+        param_types: list[ts.ColumnType] | None = None,
+        return_type: ts.ColumnType | None = None,
+        type_substitutions: dict | None = None,
         is_cls_method: bool = False,
     ) -> Signature:
         """Create a signature for the given Callable.
@@ -308,5 +334,6 @@ class Signature:
                 raise excs.Error('Cannot infer pixeltable return type')
         else:
             _, return_is_batched = cls._infer_type(sig.return_annotation)
+        system_params = [param_name for param_name in sig.parameters if param_name in cls.SYSTEM_PARAM_NAMES]
 
-        return Signature(return_type, parameters, return_is_batched)
+        return Signature(return_type, parameters, return_is_batched, system_parameters=system_params)

pixeltable/func/tools.py

@@ -1,8 +1,9 @@
-from typing import TYPE_CHECKING, Any, Callable, Optional, TypeVar, Union
+import json
+from typing import TYPE_CHECKING, Any, Callable, TypeVar
 
 import pydantic
 
-from pixeltable import exceptions as excs
+from pixeltable import exceptions as excs, type_system as ts
 
 from .function import Function
 from .signature import Parameter
@@ -28,8 +29,8 @@ class Tool(pydantic.BaseModel):
     model_config = pydantic.ConfigDict(arbitrary_types_allowed=True)
 
     fn: Function
-    name: Optional[str] = None
-    description: Optional[str] = None
+    name: str | None = None
+    description: str | None = None
 
     @property
     def parameters(self) -> dict[str, Parameter]:
@@ -69,13 +70,15 @@ class Tool(pydantic.BaseModel):
             return _extract_float_tool_arg(kwargs, param_name=param.name)
         if param.col_type.is_bool_type():
             return _extract_bool_tool_arg(kwargs, param_name=param.name)
-        raise AssertionError()
+        if param.col_type.is_json_type():
+            return _extract_json_tool_arg(kwargs, param_name=param.name)
+        raise AssertionError(param.col_type)
 
 
 class ToolChoice(pydantic.BaseModel):
     auto: bool
     required: bool
-    tool: Optional[str]
+    tool: str | None
     parallel_tool_calls: bool
 
 
@@ -97,12 +100,12 @@ class Tools(pydantic.BaseModel):
         self,
         auto: bool = False,
         required: bool = False,
-        tool: Union[str, Function, None] = None,
+        tool: str | Function | None = None,
         parallel_tool_calls: bool = True,
     ) -> ToolChoice:
         if sum([auto, required, tool is not None]) != 1:
             raise excs.Error('Exactly one of `auto`, `required`, or `tool` must be specified.')
-        tool_name: Optional[str] = None
+        tool_name: str | None = None
         if tool is not None:
             try:
                 tool_obj = next(
@@ -118,29 +121,36 @@ class Tools(pydantic.BaseModel):
 
 
 @udf
-def _extract_str_tool_arg(kwargs: dict[str, Any], param_name: str) -> Optional[str]:
+def _extract_str_tool_arg(kwargs: dict[str, Any], param_name: str) -> str | None:
     return _extract_arg(str, kwargs, param_name)
 
 
 @udf
-def _extract_int_tool_arg(kwargs: dict[str, Any], param_name: str) -> Optional[int]:
+def _extract_int_tool_arg(kwargs: dict[str, Any], param_name: str) -> int | None:
     return _extract_arg(int, kwargs, param_name)
 
 
 @udf
-def _extract_float_tool_arg(kwargs: dict[str, Any], param_name: str) -> Optional[float]:
+def _extract_float_tool_arg(kwargs: dict[str, Any], param_name: str) -> float | None:
     return _extract_arg(float, kwargs, param_name)
 
 
 @udf
-def _extract_bool_tool_arg(kwargs: dict[str, Any], param_name: str) -> Optional[bool]:
+def _extract_bool_tool_arg(kwargs: dict[str, Any], param_name: str) -> bool | None:
     return _extract_arg(bool, kwargs, param_name)
 
 
+@udf
+def _extract_json_tool_arg(kwargs: dict[str, Any], param_name: str) -> ts.Json | None:
+    if param_name in kwargs:
+        return json.loads(kwargs[param_name])
+    return None
+
+
 T = TypeVar('T')
 
 
-def _extract_arg(eval_fn: Callable[[Any], T], kwargs: dict[str, Any], param_name: str) -> Optional[T]:
+def _extract_arg(eval_fn: Callable[[Any], T], kwargs: dict[str, Any], param_name: str) -> T | None:
     if param_name in kwargs:
         return eval_fn(kwargs[param_name])
     return None

pixeltable/func/udf.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import inspect
-from typing import TYPE_CHECKING, Any, Callable, Optional, Sequence, overload
+from typing import TYPE_CHECKING, Any, Callable, Sequence, overload
 
 import pixeltable.exceptions as excs
 import pixeltable.type_system as ts
@@ -26,12 +26,12 @@ def udf(decorated_fn: Callable) -> CallableFunction: ...
 @overload
 def udf(
     *,
-    batch_size: Optional[int] = None,
-    substitute_fn: Optional[Callable] = None,
+    batch_size: int | None = None,
+    substitute_fn: Callable | None = None,
     is_method: bool = False,
     is_property: bool = False,
-    resource_pool: Optional[str] = None,
-    type_substitutions: Optional[Sequence[dict]] = None,
+    resource_pool: str | None = None,
+    type_substitutions: Sequence[dict] | None = None,
     _force_stored: bool = False,
 ) -> Callable[[Callable], CallableFunction]: ...
 
@@ -39,7 +39,7 @@ def udf(
 # pxt.udf() called explicitly on a Table:
 @overload
 def udf(
-    table: catalog.Table, /, *, return_value: Any = None, description: Optional[str] = None
+    table: catalog.Table, /, *, return_value: Any = None, description: str | None = None
 ) -> ExprTemplateFunction: ...
 
 
@@ -96,15 +96,15 @@ def udf(*args, **kwargs):  # type: ignore[no-untyped-def]
 
 def make_function(
     decorated_fn: Callable,
-    return_type: Optional[ts.ColumnType] = None,
-    param_types: Optional[list[ts.ColumnType]] = None,
-    batch_size: Optional[int] = None,
-    substitute_fn: Optional[Callable] = None,
+    return_type: ts.ColumnType | None = None,
+    param_types: list[ts.ColumnType] | None = None,
+    batch_size: int | None = None,
+    substitute_fn: Callable | None = None,
     is_method: bool = False,
     is_property: bool = False,
-    resource_pool: Optional[str] = None,
-    type_substitutions: Optional[Sequence[dict]] = None,
-    function_name: Optional[str] = None,
+    resource_pool: str | None = None,
+    type_substitutions: Sequence[dict] | None = None,
+    function_name: str | None = None,
     force_stored: bool = False,
 ) -> CallableFunction:
     """
@@ -201,11 +201,11 @@ def expr_udf(py_fn: Callable) -> ExprTemplateFunction: ...
 
 
 @overload
-def expr_udf(*, param_types: Optional[list[ts.ColumnType]] = None) -> Callable[[Callable], ExprTemplateFunction]: ...
+def expr_udf(*, param_types: list[ts.ColumnType] | None = None) -> Callable[[Callable], ExprTemplateFunction]: ...
 
 
 def expr_udf(*args: Any, **kwargs: Any) -> Any:
-    def make_expr_template(py_fn: Callable, param_types: Optional[list[ts.ColumnType]]) -> ExprTemplateFunction:
+    def make_expr_template(py_fn: Callable, param_types: list[ts.ColumnType] | None) -> ExprTemplateFunction:
         from pixeltable import exprs
 
         if py_fn.__module__ != '__main__' and py_fn.__name__.isidentifier():
@@ -237,9 +237,7 @@ def expr_udf(*args: Any, **kwargs: Any) -> Any:
         return lambda py_fn: make_expr_template(py_fn, kwargs['param_types'])
 
 
-def from_table(
-    tbl: catalog.Table, return_value: Optional['exprs.Expr'], description: Optional[str]
-) -> ExprTemplateFunction:
+def from_table(tbl: catalog.Table, return_value: 'exprs.Expr' | None, description: str | None) -> ExprTemplateFunction:
     """
     Constructs an `ExprTemplateFunction` from a `Table`.
 
@@ -262,7 +260,7 @@ def from_table(
     """
     from pixeltable import exprs
 
-    ancestors = [tbl, *tbl._base_tables]
+    ancestors = [tbl, *tbl._get_base_tables()]
     ancestors.reverse()  # We must traverse the ancestors in order from base to derived
 
     subst: dict[exprs.Expr, exprs.Expr] = {}
@@ -297,7 +295,7 @@ def from_table(
 
     if description is None:
         # Default description is the table comment
-        description = tbl._comment
+        description = tbl._get_comment()
         if len(description) == 0:
             description = f"UDF for table '{tbl._name}'"
 

pixeltable/functions/__init__.py

@@ -10,6 +10,7 @@ from . import (
     deepseek,
     fireworks,
     gemini,
+    groq,
     huggingface,
     image,
     json,
@@ -18,13 +19,18 @@ from . import (
     mistralai,
     ollama,
     openai,
+    openrouter,
     replicate,
+    reve,
     string,
     timestamp,
     together,
+    twelvelabs,
     video,
     vision,
     whisper,
+    whisperx,
+    yolox,
 )
 from .globals import count, map, max, mean, min, sum
 

pixeltable/functions/anthropic.py

@@ -8,7 +8,7 @@ the [Working with Anthropic](https://pixeltable.readme.io/docs/working-with-anth
 import datetime
 import json
 import logging
-from typing import TYPE_CHECKING, Any, Iterable, Optional, cast
+from typing import TYPE_CHECKING, Any, Iterable, cast
 
 import httpx
 
@@ -38,6 +38,64 @@ def _anthropic_client() -> 'anthropic.AsyncAnthropic':
     return env.Env.get().get_client('anthropic')
 
 
+def _get_header_info(
+    headers: httpx.Headers,
+) -> tuple[
+    tuple[int, int, datetime.datetime] | None,
+    tuple[int, int, datetime.datetime] | None,
+    tuple[int, int, datetime.datetime] | None,
+]:
+    """Extract rate limit info from Anthropic API response headers."""
+    requests_limit_str = headers.get('anthropic-ratelimit-requests-limit')
+    requests_limit = int(requests_limit_str) if requests_limit_str is not None else None
+    requests_remaining_str = headers.get('anthropic-ratelimit-requests-remaining')
+    requests_remaining = int(requests_remaining_str) if requests_remaining_str is not None else None
+    requests_reset_str = headers.get('anthropic-ratelimit-requests-reset')
+    requests_reset = (
+        datetime.datetime.fromisoformat(requests_reset_str.replace('Z', '+00:00')) if requests_reset_str else None
+    )
+    requests_info = (
+        (requests_limit, requests_remaining, requests_reset) if requests_reset and requests_remaining else None
+    )
+
+    input_tokens_limit_str = headers.get('anthropic-ratelimit-input-tokens-limit')
+    input_tokens_limit = int(input_tokens_limit_str) if input_tokens_limit_str is not None else None
+    input_tokens_remaining_str = headers.get('anthropic-ratelimit-input-tokens-remaining')
+    input_tokens_remaining = int(input_tokens_remaining_str) if input_tokens_remaining_str is not None else None
+    input_tokens_reset_str = headers.get('anthropic-ratelimit-input-tokens-reset')
+    input_tokens_reset = (
+        datetime.datetime.fromisoformat(input_tokens_reset_str.replace('Z', '+00:00'))
+        if input_tokens_reset_str
+        else None
+    )
+    input_tokens_info = (
+        (input_tokens_limit, input_tokens_remaining, input_tokens_reset)
+        if input_tokens_reset and input_tokens_remaining
+        else None
+    )
+
+    output_tokens_limit_str = headers.get('anthropic-ratelimit-output-tokens-limit')
+    output_tokens_limit = int(output_tokens_limit_str) if output_tokens_limit_str is not None else None
+    output_tokens_remaining_str = headers.get('anthropic-ratelimit-output-tokens-remaining')
+    output_tokens_remaining = int(output_tokens_remaining_str) if output_tokens_remaining_str is not None else None
+    output_tokens_reset_str = headers.get('anthropic-ratelimit-output-tokens-reset')
+    output_tokens_reset = (
+        datetime.datetime.fromisoformat(output_tokens_reset_str.replace('Z', '+00:00'))
+        if output_tokens_reset_str
+        else None
+    )
+    output_tokens_info = (
+        (output_tokens_limit, output_tokens_remaining, output_tokens_reset)
+        if output_tokens_reset and output_tokens_remaining
+        else None
+    )
+
+    if requests_info is None or input_tokens_info is None or output_tokens_info is None:
+        _logger.debug(f'get_header_info(): incomplete rate limit info: {headers}')
+
+    return requests_info, input_tokens_info, output_tokens_info
+
+
 class AnthropicRateLimitsInfo(env.RateLimitsInfo):
     def __init__(self) -> None:
         super().__init__(self._get_request_resources)
@@ -51,7 +109,28 @@ class AnthropicRateLimitsInfo(env.RateLimitsInfo):
                 input_len += len(message['content'])
         return {'requests': 1, 'input_tokens': int(input_len / 4), 'output_tokens': max_tokens}
 
-    def get_retry_delay(self, exc: Exception) -> Optional[float]:
+    def record_exc(self, exc: Exception) -> None:
+        import anthropic
+
+        if (
+            not isinstance(exc, anthropic.APIError)
+            or not hasattr(exc, 'response')
+            or not hasattr(exc.response, 'headers')
+        ):
+            return
+        requests_info, input_tokens_info, output_tokens_info = _get_header_info(exc.response.headers)
+        _logger.debug(
+            f'record_exc(): requests_info={requests_info} input_tokens_info={input_tokens_info} '
+            f'output_tokens_info={output_tokens_info}'
+        )
+        self.record(requests=requests_info, input_tokens=input_tokens_info, output_tokens=output_tokens_info)
+        self.has_exc = True
+
+        retry_after_str = exc.response.headers.get('retry-after')
+        if retry_after_str is not None:
+            _logger.debug(f'retry-after: {retry_after_str}')
+
+    def get_retry_delay(self, exc: Exception) -> float | None:
         import anthropic
 
         # deal with timeouts separately, they don't come with headers
@@ -64,8 +143,7 @@ class AnthropicRateLimitsInfo(env.RateLimitsInfo):
         should_retry_str = exc.response.headers.get('x-should-retry', '')
         if should_retry_str.lower() != 'true':
             return None
-        retry_after_str = exc.response.headers.get('retry-after', '1')
-        return int(retry_after_str)
+        return super().get_retry_delay(exc)
 
 
 @pxt.udf
@@ -74,9 +152,10 @@ async def messages(
     *,
     model: str,
     max_tokens: int,
-    model_kwargs: Optional[dict[str, Any]] = None,
-    tools: Optional[list[dict[str, Any]]] = None,
-    tool_choice: Optional[dict[str, Any]] = None,
+    model_kwargs: dict[str, Any] | None = None,
+    tools: list[dict[str, Any]] | None = None,
+    tool_choice: dict[str, Any] | None = None,
+    _runtime_ctx: env.RuntimeCtx | None = None,
 ) -> dict:
     """
     Create a Message.
@@ -151,32 +230,13 @@ async def messages(
         messages=cast(Iterable[MessageParam], messages), model=model, max_tokens=max_tokens, **model_kwargs
     )
 
-    requests_limit_str = result.headers.get('anthropic-ratelimit-requests-limit')
-    requests_limit = int(requests_limit_str) if requests_limit_str is not None else None
-    requests_remaining_str = result.headers.get('anthropic-ratelimit-requests-remaining')
-    requests_remaining = int(requests_remaining_str) if requests_remaining_str is not None else None
-    requests_reset_str = result.headers.get('anthropic-ratelimit-requests-reset')
-    requests_reset = datetime.datetime.fromisoformat(requests_reset_str.replace('Z', '+00:00'))
-    input_tokens_limit_str = result.headers.get('anthropic-ratelimit-input-tokens-limit')
-    input_tokens_limit = int(input_tokens_limit_str) if input_tokens_limit_str is not None else None
-    input_tokens_remaining_str = result.headers.get('anthropic-ratelimit-input-tokens-remaining')
-    input_tokens_remaining = int(input_tokens_remaining_str) if input_tokens_remaining_str is not None else None
-    input_tokens_reset_str = result.headers.get('anthropic-ratelimit-input-tokens-reset')
-    input_tokens_reset = datetime.datetime.fromisoformat(input_tokens_reset_str.replace('Z', '+00:00'))
-    output_tokens_limit_str = result.headers.get('anthropic-ratelimit-output-tokens-limit')
-    output_tokens_limit = int(output_tokens_limit_str) if output_tokens_limit_str is not None else None
-    output_tokens_remaining_str = result.headers.get('anthropic-ratelimit-output-tokens-remaining')
-    output_tokens_remaining = int(output_tokens_remaining_str) if output_tokens_remaining_str is not None else None
-    output_tokens_reset_str = result.headers.get('anthropic-ratelimit-output-tokens-reset')
-    output_tokens_reset = datetime.datetime.fromisoformat(output_tokens_reset_str.replace('Z', '+00:00'))
-    retry_after_str = result.headers.get('retry-after')
-    if retry_after_str is not None:
-        _logger.debug(f'retry-after: {retry_after_str}')
-
+    requests_info, input_tokens_info, output_tokens_info = _get_header_info(result.headers)
+    # retry_after_str = result.headers.get('retry-after')
+    # if retry_after_str is not None:
+    #     _logger.debug(f'retry-after: {retry_after_str}')
+    is_retry = _runtime_ctx is not None and _runtime_ctx.is_retry
     rate_limits_info.record(
-        requests=(requests_limit, requests_remaining, requests_reset),
-        input_tokens=(input_tokens_limit, input_tokens_remaining, input_tokens_reset),
-        output_tokens=(output_tokens_limit, output_tokens_remaining, output_tokens_reset),
+        requests=requests_info, input_tokens=input_tokens_info, output_tokens=output_tokens_info, reset_exc=is_retry
     )
 
     result_dict = json.loads(result.text)
@@ -194,7 +254,7 @@ def invoke_tools(tools: Tools, response: exprs.Expr) -> exprs.InlineDict:
 
 
 @pxt.udf
-def _anthropic_response_to_pxt_tool_calls(response: dict) -> Optional[dict]:
+def _anthropic_response_to_pxt_tool_calls(response: dict) -> dict | None:
     anthropic_tool_calls = [r for r in response['content'] if r['type'] == 'tool_use']
     if len(anthropic_tool_calls) == 0:
         return None

pixeltable/functions/audio.py

@@ -1,26 +1,130 @@
 """
 Pixeltable [UDFs](https://pixeltable.readme.io/docs/user-defined-functions-udfs) for `AudioType`.
-
-Example:
-```python
-import pixeltable as pxt
-import pixeltable.functions as pxtf
-
-t = pxt.get_table(...)
-t.select(pxtf.audio.get_metadata()).collect()
-```
 """
 
+import av
+import numpy as np
+
 import pixeltable as pxt
+import pixeltable.utils.av as av_utils
 from pixeltable.utils.code import local_public_names
+from pixeltable.utils.local_store import TempStore
 
 
 @pxt.udf(is_method=True)
 def get_metadata(audio: pxt.Audio) -> dict:
     """
     Gets various metadata associated with an audio file and returns it as a dictionary.
+
+    Args:
+        audio: The audio to get metadata for.
+
+    Returns:
+        A `dict` such as the following:
+
+            ```json
+            {
+                'size': 2568827,
+                'streams': [
+                    {
+                        'type': 'audio',
+                        'frames': 0,
+                        'duration': 2646000,
+                        'metadata': {},
+                        'time_base': 2.2675736961451248e-05,
+                        'codec_context': {
+                            'name': 'flac',
+                            'profile': None,
+                            'channels': 1,
+                            'codec_tag': '\\x00\\x00\\x00\\x00',
+                        },
+                        'duration_seconds': 60.0,
+                    }
+                ],
+                'bit_rate': 342510,
+                'metadata': {'encoder': 'Lavf61.1.100'},
+                'bit_exact': False,
+            }
+            ```
+
+    Examples:
+        Extract metadata for files in the `audio_col` column of the table `tbl`:
+
+        >>> tbl.select(tbl.audio_col.get_metadata()).collect()
+    """
+    return av_utils.get_metadata(audio)
+
+
+@pxt.udf()
+def encode_audio(
+    audio_data: pxt.Array[pxt.Float], *, input_sample_rate: int, format: str, output_sample_rate: int | None = None
+) -> pxt.Audio:
+    """
+    Encodes an audio clip represented as an array into a specified audio format.
+
+    Parameters:
+        audio_data: An array of sampled amplitudes. The accepted array shapes are `(N,)` or `(1, N)` for mono audio
+            or `(2, N)` for stereo.
+        input_sample_rate: The sample rate of the input audio data.
+        format: The desired output audio format. The supported formats are 'wav', 'mp3', 'flac', and 'mp4'.
+        output_sample_rate: The desired sample rate for the output audio. Defaults to the input sample rate if
+            unspecified.
+
+    Examples:
+        Add a computed column with encoded FLAC audio files to a table with audio data (as arrays of floats) and sample
+        rates:
+
+        ```
+        t.add_computed_column(
+            audio_file=encode_audio(
+                t.audio_data, input_sample_rate=t.sample_rate, format='flac'
+            )
+        )
+        ```
     """
-    return pxt.functions.video._get_metadata(audio)
+    if format not in av_utils.AUDIO_FORMATS:
+        raise pxt.Error(f'Only the following formats are supported: {av_utils.AUDIO_FORMATS.keys()}')
+    if output_sample_rate is None:
+        output_sample_rate = input_sample_rate
+
+    codec, ext = av_utils.AUDIO_FORMATS[format]
+    output_path = str(TempStore.create_path(extension=f'.{ext}'))
+
+    match audio_data.shape:
+        case (_,):
+            # Mono audio as 1D array, reshape for pyav
+            layout = 'mono'
+            audio_data_transformed = audio_data[None, :]
+        case (1, _):
+            # Mono audio as 2D array, simply reshape and transpose the input for pyav
+            layout = 'mono'
+            audio_data_transformed = audio_data.reshape(-1, 1).transpose()
+        case (2, _):
+            # Stereo audio. Input layout: [[L0, L1, L2, ...],[R0, R1, R2, ...]],
+            # pyav expects: [L0, R0, L1, R1, L2, R2, ...]
+            layout = 'stereo'
+            audio_data_transformed = np.empty(audio_data.shape[1] * 2, dtype=audio_data.dtype)
+            audio_data_transformed[0::2] = audio_data[0]
+            audio_data_transformed[1::2] = audio_data[1]
+            audio_data_transformed = audio_data_transformed.reshape(1, -1)
+        case _:
+            raise pxt.Error(
+                f'Supported input array shapes are (N,), (1, N) for mono and (2, N) for stereo, got {audio_data.shape}'
+            )
+
+    with av.open(output_path, mode='w') as output_container:
+        stream = output_container.add_stream(codec, rate=output_sample_rate)
+        assert isinstance(stream, av.AudioStream)
+
+        frame = av.AudioFrame.from_ndarray(audio_data_transformed, format='flt', layout=layout)
+        frame.sample_rate = input_sample_rate
+
+        for packet in stream.encode(frame):
+            output_container.mux(packet)
+        for packet in stream.encode():
+            output_container.mux(packet)
+
+        return output_path
 
 
 __all__ = local_public_names(__name__)