- en: StreamWriter Basic Usage
  id: totrans-0
  prefs:
  - PREF_H1
  type: TYPE_NORMAL
- en: 原文：[https://pytorch.org/audio/stable/tutorials/streamwriter_basic_tutorial.html](https://pytorch.org/audio/stable/tutorials/streamwriter_basic_tutorial.html)
  id: totrans-1
  prefs:
  - PREF_BQ
  type: TYPE_NORMAL
- en: Note
  id: totrans-2
  prefs: []
  type: TYPE_NORMAL
- en: Click [here](#sphx-glr-download-tutorials-streamwriter-basic-tutorial-py) to
    download the full example code
  id: totrans-3
  prefs: []
  type: TYPE_NORMAL
- en: '**Author**: [Moto Hira](mailto:moto%40meta.com)'
  id: totrans-4
  prefs: []
  type: TYPE_NORMAL
- en: This tutorial shows how to use [`torchaudio.io.StreamWriter`](../generated/torchaudio.io.StreamWriter.html#torchaudio.io.StreamWriter
    "torchaudio.io.StreamWriter") to encode and save audio/video data into various
    formats/destinations.
  id: totrans-5
  prefs: []
  type: TYPE_NORMAL
- en: Note
  id: totrans-6
  prefs: []
  type: TYPE_NORMAL
- en: This tutorial requires FFmpeg libraries. Please refer to [FFmpeg dependency](../installation.html#ffmpeg-dependency)
    for the detail.
  id: totrans-7
  prefs: []
  type: TYPE_NORMAL
- en: Warning
  id: totrans-8
  prefs: []
  type: TYPE_NORMAL
- en: TorchAudio dynamically loads compatible FFmpeg libraries installed on the system.
    The types of supported formats (media format, encoder, encoder options, etc) depend
    on the libraries.
  id: totrans-9
  prefs: []
  type: TYPE_NORMAL
- en: To check the available muxers and encoders, you can use the following command
  id: totrans-10
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE0]'
  id: totrans-11
  prefs: []
  type: TYPE_PRE
  zh: '[PRE0]'
- en: Preparation[](#preparation "Permalink to this heading")
  id: totrans-12
  prefs:
  - PREF_H2
  type: TYPE_NORMAL
- en: '[PRE1]'
  id: totrans-13
  prefs: []
  type: TYPE_PRE
  zh: '[PRE1]'
- en: '[PRE2]'
  id: totrans-14
  prefs: []
  type: TYPE_PRE
  zh: '[PRE2]'
- en: '[PRE3]'
  id: totrans-15
  prefs: []
  type: TYPE_PRE
  zh: '[PRE3]'
- en: The basic usage[](#the-basic-usage "Permalink to this heading")
  id: totrans-16
  prefs:
  - PREF_H2
  type: TYPE_NORMAL
- en: To save Tensor data into media formats with StreamWriter, there are three necessary
    steps
  id: totrans-17
  prefs: []
  type: TYPE_NORMAL
- en: Specify the output
  id: totrans-18
  prefs:
  - PREF_OL
  type: TYPE_NORMAL
- en: Configure streams
  id: totrans-19
  prefs:
  - PREF_OL
  type: TYPE_NORMAL
- en: Write data
  id: totrans-20
  prefs:
  - PREF_OL
  type: TYPE_NORMAL
- en: The following code illustrates how to save audio data as WAV file.
  id: totrans-21
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE4]'
  id: totrans-22
  prefs: []
  type: TYPE_PRE
  zh: '[PRE4]'
- en: '[PRE5]'
  id: totrans-23
  prefs: []
  type: TYPE_PRE
  zh: '[PRE5]'
- en: '[PRE6]'
  id: totrans-24
  prefs: []
  type: TYPE_PRE
  zh: '[PRE6]'
- en: '[PRE7]'
  id: totrans-25
  prefs: []
  type: TYPE_PRE
  zh: '[PRE7]'
- en: null
  id: totrans-26
  prefs: []
  type: TYPE_NORMAL
- en: Your browser does not support the audio element.
  id: totrans-27
  prefs: []
  type: TYPE_NORMAL
- en: Now we look into each step in more detail.
  id: totrans-28
  prefs: []
  type: TYPE_NORMAL
- en: Write destination[](#write-destination "Permalink to this heading")
  id: totrans-29
  prefs:
  - PREF_H2
  type: TYPE_NORMAL
- en: StreamWriter supports different types of write destinations
  id: totrans-30
  prefs: []
  type: TYPE_NORMAL
- en: Local files
  id: totrans-31
  prefs:
  - PREF_OL
  type: TYPE_NORMAL
- en: File-like objects
  id: totrans-32
  prefs:
  - PREF_OL
  type: TYPE_NORMAL
- en: Streaming protocols (such as RTMP and UDP)
  id: totrans-33
  prefs:
  - PREF_OL
  type: TYPE_NORMAL
- en: Media devices (speakers and video players) †
  id: totrans-34
  prefs:
  - PREF_OL
  type: TYPE_NORMAL
- en: † For media devices, please refer to [StreamWriter Advanced Usages](./streamwriter_advanced.html).
  id: totrans-35
  prefs: []
  type: TYPE_NORMAL
- en: Local files[](#local-files "Permalink to this heading")
  id: totrans-36
  prefs:
  - PREF_H3
  type: TYPE_NORMAL
- en: StreamWriter supports saving media to local files.
  id: totrans-37
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE8]'
  id: totrans-38
  prefs: []
  type: TYPE_PRE
  zh: '[PRE8]'
- en: This works for still images and videos as well.
  id: totrans-39
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE9]'
  id: totrans-40
  prefs: []
  type: TYPE_PRE
  zh: '[PRE9]'
- en: File-like objects[](#file-like-objects "Permalink to this heading")
  id: totrans-41
  prefs:
  - PREF_H3
  type: TYPE_NORMAL
- en: You can also pass a file-lie object. A file-like object must implement `write`
    method conforming to [`io.RawIOBase.write`](https://docs.python.org/3/library/io.html#io.RawIOBase.write
    "(in Python v3.12)").
  id: totrans-42
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE10]'
  id: totrans-43
  prefs: []
  type: TYPE_PRE
  zh: '[PRE10]'
- en: '[PRE11]'
  id: totrans-44
  prefs: []
  type: TYPE_PRE
  zh: '[PRE11]'
- en: Streaming protocols[](#streaming-protocols "Permalink to this heading")
  id: totrans-45
  prefs:
  - PREF_H3
  type: TYPE_NORMAL
- en: You can stream the media with streaming protocols
  id: totrans-46
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE12]'
  id: totrans-47
  prefs: []
  type: TYPE_PRE
  zh: '[PRE12]'
- en: Configuring output streams[](#configuring-output-streams "Permalink to this
    heading")
  id: totrans-48
  prefs:
  - PREF_H2
  type: TYPE_NORMAL
- en: Once the destination is specified, the next step is to configure the streams.
    For typical audio and still image cases, only one stream is required, but for
    video with audio, at least two streams (one for audio and the other for video)
    need to be configured.
  id: totrans-49
  prefs: []
  type: TYPE_NORMAL
- en: Audio Stream[](#audio-stream "Permalink to this heading")
  id: totrans-50
  prefs:
  - PREF_H3
  type: TYPE_NORMAL
- en: An audio stream can be added with `add_audio_stream()` method.
  id: totrans-51
  prefs: []
  type: TYPE_NORMAL
- en: For writing regular audio files, at minimum `sample_rate` and `num_channels`
    are required.
  id: totrans-52
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE13]'
  id: totrans-53
  prefs: []
  type: TYPE_PRE
  zh: '[PRE13]'
- en: By default, audio streams expect the input waveform tensors to be `torch.float32`
    type. If the above case, the data will be encoded into the detault encoding format
    of WAV format, which is 16-bit signed integer Linear PCM. StreamWriter converts
    the sample format internally.
  id: totrans-54
  prefs: []
  type: TYPE_NORMAL
- en: If the encoder supports multiple sample formats and you want to change the encoder
    sample format, you can use `encoder_format` option.
  id: totrans-55
  prefs: []
  type: TYPE_NORMAL
- en: In the following example, the StreamWriter expects the data type of the input
    waveform Tensor to be `torch.float32`, but it will convert the sample to 16-bit
    signed integer when encoding.
  id: totrans-56
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE14]'
  id: totrans-57
  prefs: []
  type: TYPE_PRE
  zh: '[PRE14]'
- en: If the data type of your waveform Tensor is something other than `torch.float32`,
    you can provide `format` option to change the expected data type.
  id: totrans-58
  prefs: []
  type: TYPE_NORMAL
- en: The following example configures StreamWriter to expect Tensor of `torch.int16`
    type.
  id: totrans-59
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE15]'
  id: totrans-60
  prefs: []
  type: TYPE_PRE
  zh: '[PRE15]'
- en: The following figure illustrates how `format` and `encoder_format` options work
    for audio streams.
  id: totrans-61
  prefs: []
  type: TYPE_NORMAL
- en: '![https://download.pytorch.org/torchaudio/tutorial-assets/streamwriter-format-audio.png](../Images/cc11e30ca877aed22f85b963e3d21750.png)'
  id: totrans-62
  prefs: []
  type: TYPE_IMG
- en: Video Stream[](#video-stream "Permalink to this heading")
  id: totrans-63
  prefs:
  - PREF_H3
  type: TYPE_NORMAL
- en: To add a still image or a video stream, you can use `add_video_stream()` method.
  id: totrans-64
  prefs: []
  type: TYPE_NORMAL
- en: At minimum, `frame_rate`, `height` and `width` are required.
  id: totrans-65
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE16]'
  id: totrans-66
  prefs: []
  type: TYPE_PRE
  zh: '[PRE16]'
- en: For still images, please use `frame_rate=1`.
  id: totrans-67
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE17]'
  id: totrans-68
  prefs: []
  type: TYPE_PRE
  zh: '[PRE17]'
- en: Similar to the audio stream, you can provide `format` and `encoder_format` option
    to controll the format of input data and encoding.
  id: totrans-69
  prefs: []
  type: TYPE_NORMAL
- en: The following example encodes video data in YUV422 format.
  id: totrans-70
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE18]'
  id: totrans-71
  prefs: []
  type: TYPE_PRE
  zh: '[PRE18]'
- en: YUV formats are commonly used in video encoding. Many YUV formats are composed
    of chroma channel of different plane size than that of luma channel. This makes
    it difficult to directly express it as `torch.Tensor` type. Therefore, StreamWriter
    will automatically convert the input video Tensor into the target format.
  id: totrans-72
  prefs: []
  type: TYPE_NORMAL
- en: StreamWriter expects the input image tensor to be 4-D (time, channel, height,
    width) and `torch.uint8` type.
  id: totrans-73
  prefs: []
  type: TYPE_NORMAL
- en: The default color channel is RGB. That is three color channels corresponding
    red, green and blue. If your input has different color channel, such as BGR and
    YUV, you can specify it with `format` option.
  id: totrans-74
  prefs: []
  type: TYPE_NORMAL
- en: The following example specifies BGR format.
  id: totrans-75
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE19]'
  id: totrans-76
  prefs: []
  type: TYPE_PRE
  zh: '[PRE19]'
- en: The following figure illustrates how `format` and `encoder_format` options work
    for video streams.
  id: totrans-77
  prefs: []
  type: TYPE_NORMAL
- en: '![https://download.pytorch.org/torchaudio/tutorial-assets/streamwriter-format-video.png](../Images/dae3b96285e227e70b2ff53781bc191c.png)'
  id: totrans-78
  prefs: []
  type: TYPE_IMG
- en: Write data[](#write-data "Permalink to this heading")
  id: totrans-79
  prefs:
  - PREF_H2
  type: TYPE_NORMAL
- en: Once streams are configured, the next step is to open the output location and
    start writing data.
  id: totrans-80
  prefs: []
  type: TYPE_NORMAL
- en: Use `open()` method to open the destination, and then write data with `write_audio_chunk()`
    and/or `write_video_chunk()`.
  id: totrans-81
  prefs: []
  type: TYPE_NORMAL
- en: Audio tensors are expected to have the shape of (time, channels), and video/image
    tensors are expected to have the shape of (time, channels, height, width).
  id: totrans-82
  prefs: []
  type: TYPE_NORMAL
- en: Channels, height and width must match the configuration of the corresponding
    stream, specified with `"format"` option.
  id: totrans-83
  prefs: []
  type: TYPE_NORMAL
- en: Tensor representing a still image must have only one frame in time dimension,
    but audio and video tensors can have arbitral number of frames in time dimension.
  id: totrans-84
  prefs: []
  type: TYPE_NORMAL
- en: The following code snippet illustrates this;
  id: totrans-85
  prefs: []
  type: TYPE_NORMAL
- en: Ex) Audio[](#ex-audio "Permalink to this heading")
  id: totrans-86
  prefs:
  - PREF_H3
  type: TYPE_NORMAL
- en: '[PRE20]'
  id: totrans-87
  prefs: []
  type: TYPE_PRE
  zh: '[PRE20]'
- en: Ex) Image[](#ex-image "Permalink to this heading")
  id: totrans-88
  prefs:
  - PREF_H3
  type: TYPE_NORMAL
- en: '[PRE21]'
  id: totrans-89
  prefs: []
  type: TYPE_PRE
  zh: '[PRE21]'
- en: Ex) Video without audio[](#ex-video-without-audio "Permalink to this heading")
  id: totrans-90
  prefs:
  - PREF_H3
  type: TYPE_NORMAL
- en: '[PRE22]'
  id: totrans-91
  prefs: []
  type: TYPE_PRE
  zh: '[PRE22]'
- en: Ex) Video with audio[](#ex-video-with-audio "Permalink to this heading")
  id: totrans-92
  prefs:
  - PREF_H3
  type: TYPE_NORMAL
- en: To write video with audio, separate streams have to be configured.
  id: totrans-93
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE23]'
  id: totrans-94
  prefs: []
  type: TYPE_PRE
  zh: '[PRE23]'
- en: Writing data chunk by chunk[](#writing-data-chunk-by-chunk "Permalink to this
    heading")
  id: totrans-95
  prefs:
  - PREF_H3
  type: TYPE_NORMAL
- en: When writing data, it is possible to split data along time dimension and write
    them by smaller chunks.
  id: totrans-96
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE24]'
  id: totrans-97
  prefs: []
  type: TYPE_PRE
  zh: '[PRE24]'
- en: '[PRE25]'
  id: totrans-98
  prefs: []
  type: TYPE_PRE
  zh: '[PRE25]'
- en: '[PRE26]'
  id: totrans-99
  prefs: []
  type: TYPE_PRE
  zh: '[PRE26]'
- en: '[PRE27]'
  id: totrans-100
  prefs: []
  type: TYPE_PRE
  zh: '[PRE27]'
- en: Example - Spectrum Visualizer[](#example-spectrum-visualizer "Permalink to this
    heading")
  id: totrans-101
  prefs:
  - PREF_H2
  type: TYPE_NORMAL
- en: In this section, we use StreamWriter to create a spectrum visualization of audio
    and save it as a video file.
  id: totrans-102
  prefs: []
  type: TYPE_NORMAL
- en: To create spectrum visualization, we use [`torchaudio.transforms.Spectrogram`](../generated/torchaudio.transforms.Spectrogram.html#torchaudio.transforms.Spectrogram
    "torchaudio.transforms.Spectrogram"), to get spectrum presentation of audio, generate
    raster images of its visualization using matplotplib, then use StreamWriter to
    convert them to video with the original audio.
  id: totrans-103
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE28]'
  id: totrans-104
  prefs: []
  type: TYPE_PRE
  zh: '[PRE28]'
- en: Prepare Data[](#prepare-data "Permalink to this heading")
  id: totrans-105
  prefs:
  - PREF_H3
  type: TYPE_NORMAL
- en: First, we prepare the spectrogram data. We use [`Spectrogram`](../generated/torchaudio.transforms.Spectrogram.html#torchaudio.transforms.Spectrogram
    "torchaudio.transforms.Spectrogram").
  id: totrans-106
  prefs: []
  type: TYPE_NORMAL
- en: We adjust `hop_length` so that one frame of the spectrogram corresponds to one
    video frame.
  id: totrans-107
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE29]'
  id: totrans-108
  prefs: []
  type: TYPE_PRE
  zh: '[PRE29]'
- en: The resulting spectrogram looks like the following.
  id: totrans-109
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE30]'
  id: totrans-110
  prefs: []
  type: TYPE_PRE
  zh: '[PRE30]'
- en: '![streamwriter basic tutorial](../Images/23bb162fe5e2ad4ea90d1784cca151d1.png)'
  id: totrans-111
  prefs: []
  type: TYPE_IMG
- en: Prepare Canvas[](#prepare-canvas "Permalink to this heading")
  id: totrans-112
  prefs:
  - PREF_H3
  type: TYPE_NORMAL
- en: We use `matplotlib` to visualize the spectrogram per frame. We create a helper
    function that plots the spectrogram data and generates a raster imager of the
    figure.
  id: totrans-113
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE31]'
  id: totrans-114
  prefs: []
  type: TYPE_PRE
  zh: '[PRE31]'
- en: Write Video[](#write-video "Permalink to this heading")
  id: totrans-115
  prefs:
  - PREF_H3
  type: TYPE_NORMAL
- en: Finally, we use StreamWriter and write video. We process one second of audio
    and video frames at a time.
  id: totrans-116
  prefs: []
  type: TYPE_NORMAL
- en: '[PRE32]'
  id: totrans-117
  prefs: []
  type: TYPE_PRE
  zh: '[PRE32]'
- en: '[PRE33]'
  id: totrans-118
  prefs: []
  type: TYPE_PRE
  zh: '[PRE33]'
- en: Result[](#result "Permalink to this heading")
  id: totrans-119
  prefs:
  - PREF_H3
  type: TYPE_NORMAL
  zh: 结果[](#result "跳转到此标题的永久链接")
- en: The result looks like below.
  id: totrans-120
  prefs: []
  type: TYPE_NORMAL
  zh: 结果如下所示。
- en: '[PRE34]'
  id: totrans-121
  prefs: []
  type: TYPE_PRE
  zh: '[PRE34]'
- en: 
  id: totrans-122
  prefs: []
  type: TYPE_NORMAL
- en: Your browser does not support the video tag.
  id: totrans-123
  prefs: []
  type: TYPE_NORMAL
  zh: 您的浏览器不支持视频标签。
- en: Carefully watching the video, it can be observed that the sound of “s” (curio**si**ty,
    be**si**des, thi**s**) has more energy allocated on higher frequency side (right
    side of the video).
  id: totrans-124
  prefs: []
  type: TYPE_NORMAL
  zh: 仔细观察视频，可以发现“s”音的声音（curio**si**ty, be**si**des, thi**s**）在高频侧（视频的右侧）有更多的能量分配。
- en: 'Tag: [`torchaudio.io`](../io.html#module-torchaudio.io "torchaudio.io")'
  id: totrans-125
  prefs: []
  type: TYPE_NORMAL
  zh: 标签：[`torchaudio.io`](../io.html#module-torchaudio.io "torchaudio.io")
- en: '**Total running time of the script:** ( 0 minutes 6.918 seconds)'
  id: totrans-126
  prefs: []
  type: TYPE_NORMAL
  zh: '**脚本的总运行时间：**（0分钟6.918秒）'
- en: '[`Download Python source code: streamwriter_basic_tutorial.py`](../_downloads/d8d57badf5e878c5beb8d32b0aefc7dd/streamwriter_basic_tutorial.py)'
  id: totrans-127
  prefs: []
  type: TYPE_NORMAL
  zh: '[`下载Python源代码：streamwriter_basic_tutorial.py`](../_downloads/d8d57badf5e878c5beb8d32b0aefc7dd/streamwriter_basic_tutorial.py)'
- en: '[`Download Jupyter notebook: streamwriter_basic_tutorial.ipynb`](../_downloads/78e5305a9c1fa517857bc0197643e56d/streamwriter_basic_tutorial.ipynb)'
  id: totrans-128
  prefs: []
  type: TYPE_NORMAL
  zh: '[`下载Jupyter笔记本：streamwriter_basic_tutorial.ipynb`](../_downloads/78e5305a9c1fa517857bc0197643e56d/streamwriter_basic_tutorial.ipynb)'
- en: '[Gallery generated by Sphinx-Gallery](https://sphinx-gallery.github.io)'
  id: totrans-129
  prefs: []
  type: TYPE_NORMAL
  zh: '[Sphinx-Gallery生成的图库](https://sphinx-gallery.github.io)'